Somantic – German Real Estate Search

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

Annotations already declare it a non-destructive, non-open-world read, and the description adds real behavioral depth: the estimate is derived from nearby comparables, `confidence` and `sample_size` encode trustworthiness, the point estimate is omitted when too few comparables back it, and the whole thing is a model output rather than an appraisal. These are failure-mode and reliability details the annotations cannot express.

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 paragraphs in a sensible order: what it does, how it sources and qualifies the estimate, then what is returned. Mostly front-loaded and tight, though the final sentence's 'no comparable listing is reproduced in it' is a borderline detail given the output schema already exists.

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, annotations, and full parameter coverage, the description fills the remaining gap by explaining comparables sourcing, trust signals, and degenerate cases. It is nearly complete; only the relationship to the sibling retrieval tools is left implicit.

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 11 inputs, including the subtle `rented` and `features` semantics. The description adds essentially no input-level meaning beyond that; its explanatory content (confidence, sample_size, point-estimate absence) concerns outputs, which the output schema covers. 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 and resource ('Estimate what a German address is worth to buy and to rent'), with explicit scope (Germany, both sale and rental valuation). It is clearly distinguishable from the sibling tools get_listing and search_listings, which retrieve existing listings rather than produce a valuation.

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?

'Works for any address, listed or not' implies you do not need a listing first, which is useful context against get_listing/search_listings, but the description never names those siblings or states when to prefer them. The only explicit directive is parameter-level ('Leave it out unless you know which it is' for `rented`), so usage is implied rather than spelled out.

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

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

Annotations already establish the read-only safety profile, and the description adds substantial non-obvious behavior: withdrawn listings fail with 'No listing', image_urls is always empty, and no description text is returned because it belongs to the advertiser at source_url. This is exactly the kind of context an agent cannot get from structured fields.

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 return contents are front-loaded in the first sentence, followed by useful edge-case notes. It is slightly repetitive, since 'advertiser's, at source_url' is stated twice in quick succession, but the overall structure is efficient and scannable.

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 enumerate return values, and it still covers the key gotchas (inactive-listing failure, always-empty image_urls, absent description text). Nothing an agent needs to call 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 description coverage is 100%, so the schema already documents 'id' (from search_listings) and the 'wohnung'/'haus' fallback behavior of 'property'. The description adds no additional parameter semantics, so the baseline of 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?

The description states a specific verb and resource: it returns 'Details of one listing: facts, Somantic's valuation, and the link to the original.' This clearly distinguishes it from search_listings (plural) in spirit, though it never explicitly contrasts itself with the sibling tools by name.

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: the agent infers this is the follow-up call to fetch a single listing, and the id link to search_listings appears only in the schema. The note about inactive listings failing is a useful context cue, but there is no explicit when-to-use/when-not guidance or named alternative.

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/closed-world/non-destructive, but the description adds substantial behavior: multi-portal copies are collapsed to the newest (so a page can hold fewer than per_page and total counts copies, not offers), last_seen means last confirmed-online, and stale offers drop out after ~3 days. These are non-obvious result-shaping rules not present in the structured fields.

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 is front-loaded and no sentence is filler; the dedup/pagination caveat is genuinely necessary. It is slightly long across four paragraphs, but each block carries distinct, useful information.

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

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

For a 24-parameter, zero-required search tool with full schema coverage and an output schema, the description closes the remaining gaps: result ordering, dedup collapsing, total-count semantics, and listing freshness. Nothing an agent needs to call or interpret results 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 100% across 24 parameters, so the schema already documents every filter. The description adds indirect context (the valuation fields that back price_below_market / price_vs_valuation_pct, and the source_url return), but no filter syntax or semantics beyond the schema, 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+resource+scope: 'Search current real-estate listings in Germany, newest first.' The search semantics are clearly distinct from the sibling get_listing (single record) and estimate_value (valuation), so an agent can select it 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?

The description never says when to use this tool versus get_listing or estimate_value, nor any preconditions or exclusions. Usage is only inferable from the purpose statement; there is no routing guidance.

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