foreclosurelistings

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description still adds genuine value with the "published only" scope and the explicit exclusion "Exam questions and answers are never returned" — a meaningful data-boundary disclosure. It stops short of describing behavior on missing inputs or error outcomes.

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

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

Two short sentences, front-loaded with the action and resource, followed immediately by the data-exclusion caveat. Nothing redundant or padded.

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 read tool with full annotations and no output schema, the description adequately covers what is returned and what is deliberately withheld. The only gap is behavior for a nonexistent or unpublished slug, which an agent would want to know.

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 slug parameter already carries a pattern, length bounds, and description. The description only restates lookup-by-slug and adds the published-only filter implication, which is close to the baseline for a fully documented 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 specific verb and resource ("Get one published academy course by its slug") and even enumerates the payload contents (objectives, lessons, FAQ). The singular "one ... course" implicitly contrasts with the listing siblings such as list_courses, but no sibling is actually named, so it falls just short of a 5.

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

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

The word "published" signals that only live courses are retrievable, which is a partial when-to-use constraint. There is no explicit guidance on when to prefer this over list_courses or a search sibling, nor what to expect for an unpublished or unknown slug.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds one genuinely useful business rule – only published resources are retrievable – but says nothing about what happens when a slug is unpublished or missing (error vs. empty result).

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 front-loaded sentence with no filler; the distinguishing scope word 'published' appears early. It is appropriately sized for a one-parameter lookup and nothing needs trimming.

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

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

For a simple read with rich annotations and a fully documented parameter, the definition is serviceable but leaves out the not-found behavior and does not route the agent away from search_listings when it lacks a slug. Those are the two gaps that would actually change an agent's decision.

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 parameter has a documented pattern, length bounds, and description, so the schema does the heavy lifting. 'By its slug' merely restates the schema field and adds no format or resolution detail.

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

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

States a specific verb and resource ('Get one ... foreclosure resource') with a meaningful scope qualifier ('published') and the lookup key ('by its slug'). It does not, however, distinguish itself from the sibling search_listings, which overlaps in that both return 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?

Usage is implied by 'by its slug' – the agent can infer this is the exact-lookup path when it already has a slug. No explicit when-to-use/when-not guidance is given, and the obvious alternative (search_listings, for when no slug is known) is never named.

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, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new information by stating the response includes the product's page and outbound link, which matters because there is no output schema. It omits not-found behavior, which keeps it below 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 front-loaded sentence with no filler; the lookup key and the returned content are both stated in one pass.

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 read tool with full annotation coverage and complete schema documentation, this is nearly sufficient. The only real gap is what happens when the slug does not resolve, which an agent would want to know.

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 slug parameter carries its own description plus a pattern, so the schema does the heavy lifting. The description's 'by its slug' restates rather than extends that, matching the baseline 3.

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 ('Get one affiliate product') and scopes it to a single-item lookup, which implicitly contrasts with the plural sibling list_products. It does not explicitly name the alternative tool, so it stops short of a 5.

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

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

'by its slug' implies the precondition that the caller already has a slug, which is useful context for choosing this over list_products or search_listings. However, no explicit when-to-use/when-not statement or named alternative appears.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond them by disclosing the returned content (counts per entity type, plus the last-change timestamp) — the only source of that information since no output schema exists.

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

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

A single front-loaded sentence with no filler; the freshness clause is tacked on efficiently. Minor ambiguity in 'places and categories' (counts of them, presumably), but no wasted sentences.

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 zero-parameter, non-destructive statistics endpoint with no output schema, the description says enough: what is counted and that it exposes a last-updated signal. Return field names and shape are left unspecified, which is the only remaining gap.

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

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

Zero parameters, so the baseline of 4 applies. The description correctly implies no filters or arguments are needed, and nothing in the text suggests a parameter that the schema does not have.

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 the number of') and enumerates exactly what is counted: published foreclosure resources, places, categories, plus a freshness timestamp. That is enough to distinguish it from the sibling list_*/search_* tools, though it never names them 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?

Usage is only implied by the name and noun list — an agent can infer this is a cheap overview call before paginating through list_listings or list_categories, but the description never says when to prefer it or when it is insufficient. No exclusions or prerequisites are given.

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, idempotent, non-destructive, and closed-world behavior, so the safety profile is fully covered elsewhere. The description contributes only the shape of each item (category + count); it says nothing about ordering, pagination, or whether counts are total or filtered.

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 front-loaded sentence with no filler; every clause carries information about what is returned. Nothing could be removed without losing meaning.

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 zero parameters, no output schema, and annotations covering the behavioral surface, the description supplies the essential missing piece: the return shape (category plus its resource count). Only ordering and count semantics are left implicit, a minor gap for such a simple 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?

The tool takes no parameters, so there is no parameter semantics to document and no room for description to add value. Baseline 4 applies for a complete absence of 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?

Names a specific verb (List) and resource (categories), and adds the payload detail that each entry carries foreclosure resource counts. It is distinguishable from siblings like list_places and list_sources by resource, though it never explicitly contrasts with them.

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?

There is no explicit when-to-use or when-not-to guidance, but for a zero-parameter enumeration tool the purpose implies its use (browsing category facets and their counts). The agent must infer that this is the entry point before drilling into other tools.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds two genuinely new facts beyond that: only published courses are returned, and each record includes level, length, pass mark and certificate validity. It does not mention ordering or what happens at the limit boundary, so it adds context without being rich.

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 sentence, front-loaded with the verb and scoped resource, then the returned fields. Every clause earns its place and there is no redundant restatement of the name.

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, zero-required read tool with complete annotations, the definition covers scope (published only) and return fields, which matters because no output schema exists. The remaining gap is result ordering and whether the 50-item cap implies truncation, which an agent might want to know before listing.

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%, with the level enum and limit bounds (1-50, default 50) fully documented in the schema. The description's mention of 'level' marginally reinforces the filter but adds no syntax, default, or pagination 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 (List) and a precisely scoped resource (published academy courses), plus the fields each result carries. It is clearly distinguishable from get_course (single item) and the unrelated list_* siblings, though no sibling is named 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?

Usage is only implied: the agent can infer this is the browse-all path as opposed to get_course for a single course, and that the optional level parameter narrows results. There is no explicit 'use this when' or exclusion statement, and nothing about what to do if no courses match.

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, idempotent, non-destructive, and closed-world, so safety is fully covered. The description adds one useful behavioral fact, the 'have foreclosure resources' filter criterion, but says nothing about result shape, hierarchy, or ordering.

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 front-loaded sentence with no filler. The scope-defining qualifier appears immediately rather than buried.

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 parameters, no output schema, and full annotation coverage, the description carries the remaining burden well by naming what is returned. Minor gap: it does not say whether results are flat or nested by country/region, which matters for a hierarchical reference list.

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 there is nothing for the description to disambiguate; a 4 baseline applies. It correctly signals that no filtering input is accepted, unlike sibling search tools.

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?

Clear verb-plus-resource: lists geographic entities (countries, regions, cities) restricted to those with foreclosure resources. The geographic scope distinguishes it implicitly from list_categories and list_sources, though no sibling is named 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?

Usage is only implied: an agent can infer this is the discovery/browse entry point for geography, but there is no statement of when to prefer it over list_categories, list_sources, or search_listings, nor any prerequisite or sequencing guidance.

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, idempotentHint=true, non-destructive and closed-world, so the safety profile is covered. The description's contribution beyond that is that results include product counts — useful, but no ordering, pagination, or empty-result behavior is disclosed.

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 short sentence with zero filler, and the key payload detail (counts) is front-loaded where the agent will read it.

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 zero-parameter, read-only listing tool with full annotation coverage, the description plus schema is enough to invoke it correctly. Minor gap: with no output schema, the exact return shape (field names, ordering) is only alluded to.

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 no parameters, so there is no parameter semantics to explain; the baseline for a zero-param tool 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 ('List the product categories') plus a distinguishing payload detail (product counts). However, it does not differentiate itself from the sibling 'list_categories', leaving an agent to guess which category lister to call.

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?

There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The only implied cue is that this variant returns counts, which the agent must infer rather than being told.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds one genuinely non-obvious data semantic — the price is a point-in-time snapshot from the day the product was checked, not a current price — but says nothing about result volume, ordering, or pagination.

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

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

Two short sentences, zero filler, with the core action and the most decision-relevant detail (price snapshot semantics) front-loaded ahead of the filter note.

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-optional-param, read-only list tool with full schema coverage and annotations, the description is largely sufficient and even hints at the returned fields (product + price). The one gap is the absence of any output schema combined with no note on pagination or result limits.

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 optional parameter carries its own type, slug pattern, and length bounds. The description only restates that the parameter filters by category, adding no syntax or behavior 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 and resource ("List the affiliate products") plus the returned payload (price as of the check date) and the filter dimension. It implicitly separates from get_product (single record) and list_categories, but never names a sibling, so the differentiation is left to inference.

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?

"Filter by product category" plus the optional parameter implies narrowing usage, but there is no explicit when-to-use guidance and no mention of when to prefer get_product, list_product_categories, or list_categories instead. Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety and side-effect profile is fully covered. The description adds only modest extra context — that each returned source carries license and refresh metadata — and says nothing about ordering, count, or whether the list can be empty.

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 tight sentence with the resource front-loaded and no filler. It is appropriately sized for a zero-argument read tool.

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

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

For a simple, closed-world, parameterless read with rich annotations, the description is nearly complete: it names the resource and the fields of each entry, which substitutes for the missing output schema. Only the return cardinality/shape details are left unstated.

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 the schema imposes nothing for the description to explain; baseline for a parameterless tool is 4. The sentence correctly implies no inputs are needed.

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 gives a specific verb and resource ('List where the foreclosure resource data comes from') and adds what each entry contains (license, refresh). This is clearly distinguishable from siblings like get_listing or get_stats, though it doesn't explicitly name an alternative to route away from.

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

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

Usage is only implied: an agent can infer it should call this when it needs provenance or licensing information for the foreclosure data. There is no statement of when to prefer this over get_stats or other listing tools, and no prerequisites or 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's main addition is the word 'published' — an important scope restriction that excludes unpublished resources. Beyond that it says nothing about pagination, result ordering, or what an empty result 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?

A single front-loaded sentence with no padding — good economy — but for an eight-parameter search tool it is under-specified rather than truly concise, leaving the reader to reconstruct behavior from the schema.

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 rich schema (100% coverage, defaults, enums, cursor pagination notes) and the readOnly/idempotent annotations fill most of the gap, and no output schema exists so return values needn't be described. Still, nothing in the description mentions that results are paginated or that facets can be combined, which an agent must infer.

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%, including slug sourcing from /places and /categories, sort defaults tied to presence of q, and cursor semantics, so the schema carries the parameter explanation. The description only echoes the facet groups (text, place, category) without adding constraints or format detail beyond them.

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') plus the resource ('published foreclosure resources') and the three facets it searches by (text, place, category). That is enough to separate it from get_listing (single item) and the list_* enumerators, though it never names those siblings 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?

There is no explicit when-to-use statement, no when-not-to-use, and no named alternative among get_listing, list_places, list_categories, list_sources or get_stats. The only signal is the verb 'Search', which weakly implies discovery when filters are known.

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