HouseJester

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds that the result is 'top businesses' inside a category, hinting at ranked/filtered output, but says nothing about how many are returned, how 'top' is ranked, 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity is part of why the differentiation gaps remain.

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 one required, fully documented parameter and annotations covering safety, only the return shape is left open. Since there is no output schema, the description should say more about what 'top businesses' means (count, fields, ranking) to be 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 coverage is 100%, so baseline is 3. The description contributes domain examples (fitted kitchens, bathrooms, flooring) that clarify what category values mean, but they are multi-word phrases while the schema demands a lowercase hyphenated slug — a mild inconsistency rather than added precision.

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?

It says it finds 'top businesses' in a home and interiors category, which conveys a verb and a resource, but the name 'category_detail' implies a category-record lookup rather than a business listing. It never distinguishes itself from search_listings or list_categories, so an agent cannot confidently separate the four similarly-scoped 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?

There is no statement of when to use this versus list_categories (enumerate categories), search_listings (search), or listing_detail. The example categories imply browsing, but the agent must infer that from the noun choice alone.

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 openWorldHint=false, so safety and scope are covered. The description adds that results are "verified" listings plus "top companies", but says nothing about result volume, ordering, pagination, or coverage limits for a given city.

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 resource type and geo scope come first. It could append one routing clause without bloat, but as written nothing is wasted.

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-only tool with no output schema, the description conveys roughly what comes back (listings, companies). It still leaves unclear how this differs from search_listings and whether results are bounded, which an agent needs to choose correctly.

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

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

Schema coverage is 100% and the single parameter is documented as a lowercase hyphenated slug, so the schema carries parameter meaning. The description's examples ("Leeds or Manchester") are capitalized, which mildly conflicts with the schema's lowercase-slug requirement rather than adding correct guidance.

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 names a concrete verb ("Find") and concrete resources ("verified home and interiors listings and top companies"), scoped to a UK city, so an agent can tell what it returns. It never differentiates itself from siblings like search_listings or listing_detail, which is the missing piece for 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?

There is no statement of when to use this instead of search_listings, listing_detail, or company_check, and no exclusions or prerequisites. The only usage signal is implicit: give it a UK city name.

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 openWorldHint=false, so the safety profile is covered. The description adds that results may be incomplete ('available registration details and reviews'), which is useful context, but says nothing about what happens when the identifier isn't found or how the two identifier types behave differently.

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 what is looked up and what comes back, with no filler or restatement of the tool 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 one-parameter, read-only lookup with no output schema, the description covers input modes and the shape of the response (registration details plus reviews). Only edge cases such as not-found behavior or identifier normalization are left unaddressed.

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 there is a single required parameter, so the baseline is 3. The description confirms the same two identifier forms but adds no format detail (e.g. whether the company number needs zero padding, or what a valid slug looks like) beyond the schema.

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

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

States a specific verb ('check') and resource ('a UK home and interiors company') with two accepted identifier types, which separates it from entity-detail siblings like listing_detail or city_detail. It stops short of explicitly naming or contrasting the sibling tools it could be confused with.

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 description conveys that you supply either a Companies House number or a HouseJester page slug, which signals when this tool is applicable. There is no explicit 'use this instead of listing_detail when...' guidance or stated preconditions.

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 openWorldHint=false, so the safety profile is covered. The description adds that results include listing counts (useful since there is no output schema) but says nothing about ordering, completeness, or response shape, so it only partly earns its keep.

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 with the resource and returned data front-loaded; the rhetorical question adds framing but no facts. Nothing is bloated, though the question form is slight 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 zero-parameter, read-only discovery tool with no output schema, the description conveys enough: what is listed (categories) and what comes back (listing counts). It could be complete with a one-clause note on ordering or how to follow up on a category, but nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-related gaps exist.

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 clear resource ('categories') and an implied verb ('browse'), and notes it returns listing counts, so an agent knows it enumerates category data. It does not explicitly contrast with the sibling 'category_detail', but 'browse categories' versus a detail tool is reasonably distinguishable.

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: 'browse' suggests discovery/overview use, and the sibling set (category_detail, search_listings) hints at alternatives, but the description never states when to pick this over category_detail or when not to call it.

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 readOnlyHint=true and openWorldHint=false, so safety and closed-world scope are covered. The description adds that results include business counts per city, which is genuinely useful return-shape information absent from annotations, but says nothing about ordering, coverage limits, or empty results.

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 core question and followed by exactly what is returned. No filler or repeated 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 zero-parameter read-only list tool with no output schema, the description covers both what it returns (cities and business counts) and its scope (UK, home and interiors). Minor gaps like result ordering or handling of cities with zero businesses are not critical here.

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; baseline 4 applies. The description correctly signals that no input filtering is required or possible.

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 resource (UK cities) and adds the filter scope — cities with home and interiors businesses on HouseJester — plus that counts are returned. This clearly separates it from city_detail (one city's details) and list_categories, 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?

Usage is only implied: an agent can infer this is the entry point for discovering cities before calling city_detail, but the description never says when to prefer it over city_detail or list_categories, nor any 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the listing is 'verified' and that the slug comes from search results, but it does not describe return behavior, possible errors, or what happens if the slug is invalid. This is adequate but not 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?

The description is a single, front-loaded sentence with no wasted words. It conveys the action, resource, and input source immediately.

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 detail-fetch tool with one required parameter, no output schema, and annotations covering safety, the description is nearly complete. It could clarify what 'details' include or whether only verified listings are returned, 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 description coverage is 100%, and the single parameter is already documented as 'Listing slug from search or category results.' The description reinforces the source of the slug, but it does not add format or validation details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('details of a verified HouseJester business listing'), and it names the required input source ('slug from search results'). It is clearly distinguishable from sibling search or list tools and from category/city detail tools by specifying a business listing.

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

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

It states the context for use: retrieve details using a slug obtained from search results. This implies the tool is for looking up a known listing rather than searching, but it does not explicitly name alternatives or exclusions (e.g., 'do not use for unverified 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 declare readOnlyHint=true and openWorldHint=false, so safety and scope are partly covered. The description adds that results are 'verified' businesses in the UK home/interiors domain, which is useful context, but it does not explain result limits, pagination, ranking, or what 'verified' 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 a single front-loaded sentence with no filler. It efficiently conveys the core search behavior and optional city filter.

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 two-parameter search with full schema coverage and read-only annotations, the description provides enough context to call the tool correctly. The only notable omission is result behavior or pagination, which is not explained.

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 both query and city are already documented with examples. The description’s example ('kitchen fitters in Leeds') reinforces the intended combination but adds little semantic detail beyond the schema.

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

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

The description states a specific verb and resource: find verified UK home and interiors businesses by keyword and optional city. It is clearly a search/list tool rather than a detail tool, though it does not explicitly distinguish itself from siblings like listing_detail or company_check.

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 through examples like kitchen fitters in Leeds, showing the intended search pattern. However, it does not say when to use this tool versus listing_detail, company_check, or category/city listing tools, nor does it state exclusions.

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