Homejourney Singapore property listings

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds substantial context beyond that: the Residential Property Act rules, the allowed/needs_sla_approval/not_allowed outcomes, next-step guidance, SLA links, the required disclaimer, and that it needs no sign-in and stores nothing about the buyer.

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 front-loaded with the use case and legal rules, then moves to parameter guidance and return values. It is dense but structured, and the legal detail and disclaimer are necessary for this tool rather than filler.

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?

An output schema exists and annotations cover the safety profile, yet the description still supplies the legal context, limitations, return statuses, next step and disclaimer needed for a complex eligibility check. Nothing essential for correct invocation appears to be 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 description coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema: listing_id or property_kind can be supplied, property_kind overrides the listing, landed listings may omit house type and never record strata-within-condo status, and GCB area comes from the listing's location.

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: checking whether a buyer may buy a landed home in Singapore, and enumerates the property types covered. It also distinguishes itself from search_listings by explaining that listing_id comes from that sibling tool.

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 says when to use it: when a buyer asks whether they may buy a landed home, or before a PR or foreigner asks to view a landed listing. It gives prerequisites such as residency and listing_id or property_kind, but does not state when not to use it or name an alternative eligibility tool.

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?

Goes well beyond the readOnly/openWorld annotations: it discloses the ranking behavior, that scores are out of 100 and null when no criterion can be judged, that reasons, tradeoffs and missing data come back, and an explicit privacy constraint that owner or agent contact details are never returned.

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?

Front-loaded with the usage condition and the input, which is the right order. The return-value sentence is very long and dense, but every clause carries information an agent would otherwise have to discover.

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 comparison tool with nested criteria and a privacy-sensitive domain, the definition covers input provenance, ranking semantics, null handling, and the rendering handoff. Nothing needed to call it correctly is missing, even though an output schema exists.

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 only 25%, and the description compensates by enumerating most criteria (budget, bedrooms, bathrooms, districts, MRT stations, max walk, min lease, must-have features) and clarifying that a saved home's property_id belongs in listing_ids. It leaves several nested fields unexplained (query, commute_note, listing_type, property_type, subletting_types) and says nothing about host or host_reference_id.

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 ('compared side by side' for two to six Homejourney listings) and names the upstream tools that produce the inputs, so it is clearly distinguished from search_listings and get_listing_details.

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 says when to use it ('after search_listings or list_saved_properties when the user wants two to six listings compared'), names the alternatives, and gives the downstream handoff ('pass it to render_shortlist' for a card).

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 readOnly, non-destructive, closed-world, so the safety profile is covered; the description adds genuinely new behavior: listing text is returned with owner/agent contact details stripped, guide text is returned whole with a Homejourney URL for citations. That redaction and citation-output disclosure is exactly the kind of context annotations cannot carry. It says nothing about failure modes for an unknown ID.

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 compact sentences, front-loaded with the core action and immediately followed by what comes back. The 'for deep-research and citation hosts' clause is dense but earns its place by scoping the audience. No filler or repetition of the 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 an output schema present, the description needn't detail return shape, and it wisely focuses on the redaction and citation-URL properties instead. Combined with the sibling routing note, an agent has enough to call it correctly; only ID-format disambiguation between listing and guide 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 0% and the single `id` property has no description, so the description must carry the load. It does establish provenance ('the ID that search returned'), which is useful, but it never clarifies whether listing and guide IDs share a namespace or format, which matters because one parameter serves both resource types.

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 (fetch) and resource (a Homejourney listing or guide) plus the keying mechanism (the ID that search returned), and names a sibling to avoid. The only ambiguity is that one tool serves two resource types, but the description makes that duality explicit rather than hiding it.

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 a clear usage context (deep-research and citation hosts) and an explicit exclusion with the alternative named: 'After search_listings, use get_listing_details instead.' It does not say when to pick this over search_guides/get_listing_details for guide content specifically, so it stops short of full when/when-not coverage.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful disclosure that no contact or address details are returned, which is a real behavioral constraint beyond the annotations, though polling/expiry behavior of the token is not mentioned.

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?

One compact sentence that front-loads the precondition and the returned fields, followed by a short disclosure. Every clause earns its place with no filler.

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 an output schema present, the description need not enumerate return structure; it only needs to establish the token source and privacy boundary. Those are covered, so nothing an agent needs to invoke this correctly 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 0% for the single parameter, so the description must compensate. It identifies the parameter as an opaque token and points to its producer, giving essential meaning. It does not restate the length bounds or format, but 'opaque' plus the origin tool is sufficient for correct use.

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 (check) and resource (checkout status via an opaque status token), and enumerates exactly what is returned: card approval, provider, completion, and payment state. It ties itself to the sibling prepare_guest_service_checkout, making the pairing 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?

Explicitly identifies the precondition — the token must come from prepare_guest_service_checkout — which tells the agent when this tool is callable. It does not name an alternative status tool or state exclusions, so it falls short of a full 5.

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?

Beyond readOnlyHint and non-destructive annotations, the description discloses substantial behavior: it lists the returned detail categories, conditional reportUrl for owner listings, tenantEligibility for HDB rentals, and the privacy constraint that owner/agent contact details are never returned. This gives the agent useful expectations about output and constraints.

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 front-loaded with the when-to-use instruction, which is good. However, it is a single very long sentence with an exhaustive enumeration of amenities and conditional fields, making it harder to scan than necessary. Much of the detail could be structured more tightly.

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 returns rich listing details and has an output schema, the description still provides enough context about special cases: owner listings, HDB rentals, tenant eligibility, and privacy limits. It covers the complexity of the tool without leaving major behavioral gaps.

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 0% for listing_id, so the description should compensate. It implies the identifier comes from search_listings and refers to one listing, but it does not explicitly explain the listing_id parameter or its UUID format. Minimum viable given the single obvious parameter.

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: get full details of one Homejourney listing. It distinguishes this from search_listings by saying to use it after search_listings for a single listing, and the enumerated detail fields make the scope 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?

It gives clear usage context: use after search_listings when the user wants full details of one listing. It also gives conditional guidance for owner listings and HDB rentals, including tenantEligibility for PR or foreign users. It does not explicitly state when not to use it or name other alternatives beyond search_listings.

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 a safe, read-only, closed-world operation. The description adds substantial behavioral context beyond annotations: no sign-in is needed, the response includes rules and examples, and it outlines the downstream sequence involving create_listing_draft, photo confirmation, Singpass verification, Pro enrollment, and publishing.

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 front-loaded with the key trigger phrase and then systematically lists response contents and workflow steps. It is dense and somewhat long with nested parentheticals, but most clauses carry useful information for an agent preparing to collect owner 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?

There is no output schema, so the description must explain the return payload, and it does so thoroughly: fields, requiredness, allowed values, examples, property-type constraints, photo rules, floor plan source, and rental rule groupings. It also covers invocation timing, no-auth behavior, and the broader publishing workflow.

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 tool takes zero parameters, so parameter semantics are inherently minimal. The description appropriately spends no time explaining nonexistent inputs and instead focuses on what the no-argument call returns and how to use it.

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: it returns the owner listing checklist for Homejourney. It enumerates exactly what the checklist contains (required/optional fields, allowed values, photo rules, floor plan ordering, HDB/URA rental rules, ordered workflow), making it clearly distinguishable from search/render/list-detail siblings.

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 invocation condition: use this first when an owner wants to sell or rent out their own home, before asking them anything. It also instructs the agent to ask for all required fields in one message. It does not name or exclude alternative tools, so it stops short of a full when/when-not/alternatives statement.

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?

The annotations declare a non-read-only, non-destructive, open-world operation, and the description adds substantive behavior beyond that: no OTP is required, it returns an authorization link, nothing is charged or held at this stage, charging happens after the job, the booking appears in the customer's account after sign-in with the same verified email or WhatsApp number, and onsite_contact is visible only to the assigned business until the job closes. These details materially supplement the annotations without contradicting them.

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 front-loaded with the use case and then packs necessary behavioral and customer-script details into one paragraph. It is longer than typical but mostly earns its length; the only structural weakness is that it is a single dense block rather than clearly separated prerequisites and behavior.

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 complex 27-parameter booking mutation with annotations and an output schema, the description covers the central flow, payment timing, account behavior, and onsite contact well. It still leaves the agent to infer the sibling-tool workflow, such as search_services or quote_service_booking, and several parameter meanings, so it is not fully complete.

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 only 44% across 27 parameters, so the description must compensate. It explains some important semantics, including customer confirmation, price, schedule, address, contact consent, and onsite_contact, but it leaves many required fields such as idempotency_key, service_type, confirmed, and the package identifiers largely to the schema or inference.

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 directive, 'Use this for new customer bookings from an external agent,' and states that it returns 'one branded Homejourney review-and-authorization link,' so the operation is clear. It does not explicitly differentiate itself from sibling tools such as quote_service_booking or get_guest_service_checkout_status, so it falls 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?

It gives a clear trigger: use after the customer confirms the selected provider package, exact price, schedule, address, customer-provided email and mobile number, and contact consent. It does not state when not to use it or name alternatives such as search_services or quote_service_booking for obtaining package details.

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?

Goes well beyond the readOnly/non-destructive annotations: it says no booking row is created, no contact details are needed, an unaccepted booking is cancelled without charge, an exact start at least two hours away is required, and slots are only returned when the address is supplied. It also enumerates refusal reason codes and what each means.

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 front-loaded with the purpose and the no-booking-row guarantee, then proceeds through slot, extras, and refusal rules. It is dense but nearly every sentence carries a behavioral rule; a bulleted structure would improve scanability without changing the content.

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 20 parameters, nested customer_info, an output schema, and multiple conditional modes (package vs operator price, address present vs absent), the description covers the important decision points and failure modes. The output schema relieved it of explaining return values, and 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?

Schema coverage is 55%, and the description compensates substantially by explaining the conditional role of the address, the extras re-quote flow, the package unit-count refusal, and the two-hour start constraint. Some parameters, such as price fields, service_frequency, and discount_amount, are still left to the schema, so it is strong but not exhaustive.

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 ('quote' a 'service booking'), and immediately distinguishes it from search_services and booking creation ('does not create a booking row'). An agent can tell what the tool returns (server-revalidated price) without opening the schema.

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 says to use it after search_services with selected provider and package identifiers, and names when to supply the address (only to list operator arrival times), when to quote again with extras, and when to quote another package or date. The alternatives and conditions are stated rather than implied.

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, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: it will never surface owner or agent contact details, which tells the agent what content to expect and what the card deliberately omits.

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 what is rendered, then when to use it, then a constraint. No filler, though the usage sentence is thin relative to the space it occupies.

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 one-parameter render tool with no output schema, the description covers what gets displayed and a key privacy constraint. It lacks only edge-case behavior such as what happens with an invalid or expired listing_id.

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 single listing_id parameter has 0% schema description coverage, but its name and uuid format are largely self-describing. The description adds nothing about the parameter (e.g., where to obtain a valid ID), so it neither compensates nor misleads.

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 concrete verb and resource — renders one Homejourney listing as a visual card with photos, details, and an open button. The 'visual card' framing separates it from the data-oriented sibling get_listing_details, though the description never names that sibling explicitly.

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?

"Use this when the user wants to look at one listing" gives a usable trigger condition, but with siblings like get_listing_details, render_shortlist, and compare_listings present, it offers no contrast or exclusion to help disambiguate a pure-data fetch from a UI render.

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=false, so the safety profile is covered. The description adds that the comparison should be passed unchanged and that the result is a visual card for hosts that can display app cards, but it does not describe validation behavior, failure modes, or exactly what rendering produces.

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 two tight sentences, front-loading the purpose and then the usage condition. Every phrase earns its place, with no redundant restatement of the 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?

The tool has a large, complex input schema with 8 parameters and no output schema, while the description gives only high-level context. It says the result is a visual shortlist card and that the comparison should be passed unchanged, but it does not compensate for the lack of parameter descriptions or clarify what rendering returns.

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 0% across 8 parameters, so the schema provides field names but no semantic explanations. The description only says to pass the comparison unchanged, which helps avoid transforming the input, but it does not explain required listings, ranking, comparedAt, criteriaSummary, or other parameters.

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: it shows a comparison returned by compare_listings as a visual shortlist card. It clearly distinguishes rendering from computing by naming compare_listings as the producer and telling the agent to pass its comparison unchanged.

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 a clear usage condition: use this after compare_listings when the host can display app cards. That is strong sequencing guidance, though it does not explicitly state when not to use it or name a fallback alternative for hosts that cannot display app cards.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral context beyond them: canonical URLs are returned, and there is a disclosed fallback path returning guide: prefixed IDs or an empty list with a note naming the next tool. It does not discuss result volume or pagination, so it falls short of the top mark.

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?

Four sentences, each doing distinct work: purpose, query construction, return value, fallback. The alternative-tool routing is placed last, after the core behavior, and there is no filler.

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 one-parameter search tool, the description covers selection, query phrasing, return semantics, and the no-match fallback, and an output schema exists so return-value details need no elaboration. Nothing an agent needs to call it correctly 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 0% and the single parameter is a bare string, so the description carries the burden — and it does add meaning by prescribing broad availability phrasing and limiting location/project/feature keywords to user-supplied ones. It stops short of stating query syntax or matching behavior, so not a 5.

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 (search) and resource (active Homejourney Singapore property listings) with a stated consumer (deep-research and citation hosts). It also distinguishes itself from the nearest sibling, search_listings, so an agent can route correctly without opening either schema.

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 declares the supported query style ('Broad availability questions are supported'), constrains keyword use to user-supplied terms, and names the alternative tool (search_listings) with the exact conditions that select it (price, bedrooms, area, rent terms).

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 a safe read (readOnlyHint true, destructiveHint false); the description adds behavior beyond them: ranking order with an area (most CEA-recorded deals in the last three years, then latest deal), what the profile payload contains, that listing ids feed get_listing_details, that contact details are never returned, and that no sign-in is required.

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 use case is front-loaded and every clause maps to a real decision point, but the single dense paragraph runs long and mixes retrieval scope, ranking, and return shape in one block. Slightly tighter segmentation would read faster.

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 6-parameter, multi-mode search with an output schema, the description covers trigger, mode selection, ranking semantics, return contents, downstream linkage and the no-contact-details constraint. Nothing an agent needs to call it correctly 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 already 83%, so the schema carries most parameter documentation. The description still adds meaning the schema does not: the sale-vs-rental ranking tradeoff, the parenthetical that 'most HDB agent deals are rentals', and the concrete landed/D10 example for property_type.

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?

Names a specific verb and resource — searching Singapore property agents by name or CEA registration number — and extends it to area/agency lookups. It is clearly distinct from siblings like search_listings, search_guides and get_listing_details, which are referenced only as downstream consumers.

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 frames the trigger ('when someone asks about a Singapore property agent... including an agent asking what Homejourney shows about them') and gives conditional guidance: pass area alone or with agency for area lookups, pass deal_type for seller/buyer vs landlord/tenant, pass property_type for one home kind. It also states what happens when these are omitted ('without it every deal counts').

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it requires no sign-in and specifies the return payload shape (URL, short answer, audience, calculator flag, last-checked date) plus an instruction to cite the URL and date.

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 trigger guidance is front-loaded, which is good, but the repeated 'Also use it when...' construction makes the middle dense and list-heavy, and the return-field and citation details could be tightened. Every element is relevant, but the prose is longer than needed for the decision it supports.

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?

An output schema exists, so the description's return-value summary is a bonus rather than a necessity, and the trigger conditions, persona semantics, and auth expectation are all present. An agent has everything needed to decide when to call it and how to construct a valid call.

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 0%, so the description must carry parameter meaning. It does explain persona (enumerating buyer, seller, renter, landlord, foreigner, agent) and query (empty means list everything for that persona), but limit — its default of 5 and maximum of 25 — is never mentioned, leaving one of three parameters undocumented.

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) and resource (Homejourney guides/help articles), then enumerates the exact topic domains covered: grants and eligibility, BTO and resale, stamp duty, loans, MOP, tenancy, agent operations, and account management. This clearly separates it from siblings like search_listings and search_agents, which target different resource types.

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?

Three explicit 'use this when' clauses give concrete trigger scenarios across consumer, agent, and account domains, plus a clear instruction to leave query empty to list all guides for a persona. It lacks an explicit 'when not to use' or a named alternative for overlapping needs, keeping it just below top marks.

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=false, so safety is covered. The description adds useful behavior beyond that: results are limited to active, published listings, contacts are never returned, pagination.total is exact, and clustered listings at one address return as one result with listingCluster naming the others. Those are real additions, but return-format detail overlaps with the existing output 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?

Front-loaded with purpose and when-to-use, then result semantics. Mostly efficient, but the clustering sentence ("the listings one agent has at one address or in one development on a page come back as one result...") is tangled, and the returns clause runs long and would read better split.

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 38-param search tool, the description covers the highest-risk unknowns: what a result set represents, that contacts are withheld, and that total is exact. An output schema exists so return shape need not be restated, and per-filter meaning is delegated to schema descriptions; the main remaining gap is pagination/limit behavior guidance.

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?

With 38 parameters at 66% schema coverage, many filters are documented only in the schema. The description adds semantics for exactly one: query is full-text over project, title, address and description, which the schema leaves undefined. Everything else it says (total counts, clustering) concerns results, not parameter meaning, so it does little to close the remaining coverage gap.

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 plus scope: "Primary listing-discovery tool for homes in Singapore", and enumerates the criteria (area, MRT, school, budget, bedrooms, flat type). The word "primary" and "listing-discovery" carve out its role against detail/compare siblings such as get_listing_details and compare_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 an explicit trigger: "Use this when the user asks what properties are available, or describes a home to buy or rent by ... criteria", plus a rule for the query param ("Omit query for a broad availability request"). It does not name the alternative tools for narrower needs (e.g. detail fetch or comparison), so exclusions are implicit 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?

Goes well beyond the readOnly/openWorld annotations: explains soldUnder and priceSetBy semantics, the dual pricing model (large operator vs. small shop), that booking saves a card, and the precise charge/hold timing for both checkout paths. It also discloses fallback diagnostics (noPackageForHomeSize, noPackageForUnits) and the conditional landedWorks block. No contradiction with readOnlyHint=true.

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?

Purpose and result shape are front-loaded, but the middle section embeds verbatim booking/checkout charge copy that belongs to sibling tools and dilutes the search framing. The aircon and home-size rules are useful, yet the paragraph is dense and would benefit from tighter separation.

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 10-parameter search with an output schema, it covers the ambiguous enumerable params, the query-text inference behavior, and the extra landedWorks return. Pagination/filter params (page, limit, provider_id, service_type) and any result-shape caveats are left to the schema, which is acceptable given an output schema exists.

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?

With only 50% schema coverage, the description carries real weight: it explains how floor_area_sqft outranks hdb_flat_type in practice, how unit_type/units/bedrooms are matched or inferred from the query string, and why unit_type narrows the trade. page, limit, provider_id and service_type remain unexplained, so it doesn't cover everything.

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?

Opens with a specific verb+resource: 'find active Homejourney services,' which is distinguishable from search_listings, search_agents and search_guides by resource alone. It never explicitly contrasts itself with those siblings, so the differentiation is implicit rather than stated.

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 concrete conditional rules: pass floor_area_sqft/hdb_flat_type/bedrooms for home-size pricing, unit_type+units for aircon, and notes that these can be inferred from the query text. It also maps outcomes to create_service_booking vs. prepare_guest_service_checkout. It stops short of explicit when-not-to-use guidance or naming non-booking siblings like quote_service_booking.

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