Domly — rentals in Bulgaria

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

The readOnlyHint annotation covers the safety profile, and with no output schema the description carries the burden of describing the return payload — which it does well by enumerating amenities, description excerpt, cross-site matches, and Domly/photo/contact links. It does not cover failure behavior for an invalid id, so it stops short of a 5.

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?

A single sentence that front-loads the core action ('Details of one rental listing by its id') before enumerating returned contents. Efficient, though the long mid-sentence list of return items slightly dilutes scanability.

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 two-parameter read tool with no output schema, the description is largely self-sufficient: it names the identifying source and sketches the response contents. Minor gaps remain around error behavior on a bad id and the role of the language parameter, but 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 100%, so both parameters (id, language enum) are already fully documented in the schema. The description's 'by its id from search_listings' merely echoes the id description and adds no syntax or format detail beyond it; 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 specific verb (get/details), a precise resource (one rental listing), and the identifying key (its id from search_listings). An agent can immediately distinguish this single-listing fetch from the sibling search_listings list operation.

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 rather than stated: 'by its id from search_listings' suggests calling this after a search to drill into one result. There is no explicit when-to-use/when-not guidance and no mention of the other siblings (get_price_stats, request_realtor), so the routing signal is only implicit.

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 only declare readOnlyHint=true, so the description adds meaningful behavior: the data comes from a daily index (freshness/periodicity), it is sourced from Domly, and the agent is obligated to cite the source with the provided url. It does not cover rate limits or error behavior, but the citation/attribution requirement is real context beyond the annotation.

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, both front-loaded: the return contents come first, followed by the usage trigger and citation rule. Every clause earns its place with no redundancy.

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 carry the return-shape burden, and it does — median rent, 25th/75th percentiles, price per m², 30-day change, and breakdowns by apartment size and district. Combined with the citation rule, an agent has everything needed to call and report on this 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 schema already documents both 'city' (slug from list_cities or name) and 'language' (enum with default). The description adds no syntax or format detail for these parameters, which is the baseline expectation when the schema carries the load.

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 (rental market statistics for a Bulgarian city from Domly's daily index) and enumerates exactly what is returned, which cleanly separates it from sibling listing/city tools. An agent can distinguish it from search_listings or get_listing without opening a schema.

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

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

Gives an explicit triggering question pattern ('how much does it cost to rent in ...') and adds a citation obligation with the given url. It stops short of naming alternatives or stating when-not to use it, so it is clear context without exclusions.

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?

readOnlyHint=true already establishes this is a safe read. The description adds genuine behavioral context the annotation does not: the covered domain (Bulgarian cities only), the metric shape (active listing count, median rent in EUR), and the dependency role (source of city slugs). It does not state freshness or ordering of the data, which is a minor gap.

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, both earning their place: the first describes content, the second describes the calling workflow. The most actionable instruction (call first) is placed last but is short and easy to retain; nothing is padded or redundant.

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 correctly compensates by describing the return fields and the slug concept, which is what downstream tools consume. For a one-optional-parameter lookup tool this is nearly complete; only data freshness/ordering is left implicit, which is acceptable given the structure.

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 'language' parameter has a documented enum with a stated default, so the schema fully carries parameter semantics. The description adds nothing about the language option, 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 specific verb ('Lists') and resource ('Bulgarian cities covered by Domly') and goes further to name the return payload: active listing counts and median monthly rent in EUR. An agent can immediately distinguish this from get_listing, get_price_stats, search_listings, and request_realtor.

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 sequencing guidance: 'Call this first to get city slugs for the other tools,' which tells the agent exactly when this tool is appropriate relative to its siblings. It does not name a tool to avoid or a when-not condition, but the entry-point role is unambiguous.

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?

With no behavioral annotations, the description carries the burden well: it discloses that the user's contact is shared with a third-party realtor, that a fallback team may handle the request, and that realtor services may be paid. It does not cover whether the request can be cancelled or what response the caller receives.

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 efficient sentences: purpose first, consent prerequisite second, cost/terms caveat third. Every sentence earns its place and there is no wasted text.

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 side-effect tool with no output schema and no behavioral annotations, the description covers the critical privacy, consent, third-party, and cost context. It leaves return behavior and cancellation unspecified, but the schema handles parameter completeness.

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 reinforces the contact and consent semantics but adds little parameter-specific detail 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 description states a specific action: sending the user's request to a local partner realtor or the Domly team, with the outcome that the realtor contacts the user and picks rental options. This is clearly distinct from the read/search/list siblings and leaves no ambiguity about what the tool does.

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 prerequisite: call only after the user explicitly agrees to share their contact for this purpose. It also explains the realtor may charge for their own services, but it does not explicitly name alternatives or when not to use this tool beyond the consent condition.

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, and the description adds useful behavior: daily collection from three sources, duplicate merging, a 10-listing cap, and the requirement to show URLs. It does not cover pagination or rate limits, but adds meaningful context beyond the annotation.

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 compact sentences, front-loaded with the core search behavior and followed by return details and a key display instruction. Every sentence adds useful information 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?

Given 12 parameters, high schema coverage, and no output schema, the description adequately explains the search scope, data sources, return fields, and URL display requirement. It could say more about retrieving additional results beyond the 10-listing cap, but is otherwise complete enough for an agent to call it.

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 high at 83%, so the schema already documents most parameters. The description mentions city scope and return fields but does not add parameter-specific meaning 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?

States a specific verb and resource: "Searches active long-term rental listings" in a Bulgarian city, including data sources and deduplication. It is clearly a search tool, though it does not explicitly name sibling tools such as get_listing or get_price_stats to differentiate use cases.

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 clear context for when this tool applies: finding active long-term rentals in a Bulgarian city, with an explicit instruction to show each listing URL. It does not state exclusions or explicitly route to alternatives, so it falls short of full usage guidance.

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