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

The description adds meaningful behavior beyond the readOnlyHint: it warns that matches always come back as candidates because names and slugs collide, and that only the numeric ID is authoritative. This is valuable context that prevents an agent from assuming a single, clean match.

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 tightly worded sentences: the first front-loads the core purpose, and the second adds only the essential caveat about collisions and ID authority. Every clause earns its place, with no fluff or repetition.

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 single-parameter read-only lookup tool with a full input schema, an output schema, and readOnlyHint annotation, the description covers the key operational caveat an agent needs. Nothing important is missing for correct invocation and interpretation.

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 query parameter is already well described as a German category name with optional parent qualification. The tool description adds general context about ambiguity but does not add new parameter-level details, so the baseline score of 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 states a specific verb and resource: finding category IDs by name. The follow-up sentence explains the result shape (candidates) and the unique identifier, distinguishing this from sibling find tools operating on locations and shops.

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 intended use is implied: call this tool when you have a category name and need the corresponding numeric category ID. However, it does not explicitly state when not to use it or name alternatives, so the guidance remains implicit rather than directive.

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 readOnlyHint=true already cover the safety profile. The description adds the behavioral trait that it always returns candidates, which is useful, but the erroneous assertion that a postcode can match contradicts the schema's statement that postcode-layer ids are absent, weakening the transparency.

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 short and front-loaded with the core purpose. However, the 'or postcode' clause is misleading and does not earn its place, since the schema explicitly denies postcode matching; a corrected version would be fully concise.

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 one-parameter, read-only lookup with an output schema, the definition is nearly complete: it covers the query format, the postcode exception, and the correct alternative tool. The only completeness gap is the internal contradiction between the top description and the parameter schema.

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 query parameter is richly documented with format, qualification syntax, and the postcode exception. The tool description adds no new parameter meaning beyond the redundant 'name or postcode' phrase, so it stays at the baseline for high schema coverage.

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 the tool returns location IDs for a name or postcode, which is a clear resource and output. However, the claim that postcodes are matched is contradicted by the parameter schema, which explicitly says a five-digit postcode matches nothing, so the stated purpose is partly misleading.

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 query parameter description gives explicit guidance: a German place name optionally qualified as 'Bundesland > Ort', and it routes postcode queries to search_listings' free-text `location` instead. It names the alternative tool and the condition for using it, leaving no ambiguity.

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 the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral details: the request is live/network-dependent, and matches may be loose profile-text mentions rather than exact name hits. This helps the agent set expectations about latency and result accuracy.

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 sentences with no filler. It front-loads the core purpose, then adds the live-request differentiator and the important matching caveat. Every sentence adds necessary operational or behavioral value.

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 output schema exists and annotations already signal safety/open-world expectations, the description covers the critical caveats: live request behavior and the possibility of profile-mention matches. It could be more complete by explaining the optional filter parameters, but the overall context is sufficient for correct invocation in most cases.

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 25%, and the description only meaningfully covers the 'name' parameter by stating it is passed to full-text search unchanged. The 'page', 'category_id', and 'location_id' parameters receive no explanation in either the schema or the description, so the agent has to infer their semantics from names alone.

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 exactly what the tool returns ('Shop slugs for COMMERCIAL sellers matching a name') and clearly distinguishes it from sibling resolvers by noting it 'makes a live request, unlike the other resolvers.' This tells the agent both the resource and the query intent without ambiguity.

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 provides useful invocation context: it performs a live request rather than using cached resolver data, and it warns that matches may be mentions in profile text rather than actual shop names. It does not explicitly name alternative tools or give strict when-not-to-use conditions, but the context is clear enough for an agent to choose correctly.

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, so the safety profile is covered. The description adds a small amount of behavioral context by saying 'in full,' indicating a complete listing is returned, but it doesn't mention edge cases like missing IDs or unavailable listings.

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 short phrase, front-loaded with the most important information: one listing, full detail, identified by ad id. 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 simple single-parameter retrieval tool with an output schema and read-only annotation, this description is complete enough. The agent knows what resource is returned, how to identify it, and can rely on the schema for the response shape.

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 compensate. 'by ad id' clearly maps the single required parameter ad_id to the identifier of the listing to fetch, which is sufficient for this one-parameter tool.

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 resource ('one listing') and the lookup mode ('in full, by ad id'), making the tool's purpose clear. It distinguishes itself from search_listings by emphasizing a single full record rather than search results, though it doesn't explicitly name alternatives.

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 implies this tool is for retrieving a single listing when you already have its ad id. It does not explicitly state when to choose it over siblings like search_listings or get_shop, leaving that inference to the agent.

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=true, so the safety profile is covered. The description adds useful context by restricting the tool to commercial sellers, but it does not disclose behavior around pagination, filtering semantics, or what happens when a private or invalid shop_slug is provided.

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 short sentences with no filler. The primary purpose and the key limitation are both front-loaded, making it easy for an agent to parse quickly.

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?

Although annotations and an output schema reduce the burden, the description is too thin for a tool with 7 parameters and 0% schema coverage. It lacks parameter semantics, pagination/filtering context, and explicit routing to sibling tools, so an agent would still have to guess important invocation details.

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%, and the description does not compensate. It only hints that shop_slug refers to a commercial seller's shop. The meaning and combined behavior of page, keywords, max_price, min_price, category_id, and location_id are left entirely unexplained, which is a significant gap for a tool with 7 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 clearly states the resource and scope: 'Profile and listings for one COMMERCIAL seller.' It distinguishes the tool from siblings by explicitly noting that private sellers have no shop page, so an agent can tell this is for a specific commercial shop rather than search listings or find shops.

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 implies when to use the tool: when a specific commercial seller's shop and inventory are needed. It also gives a clear exclusion: private sellers are not reachable. However, it does not explicitly name sibling alternatives such as find_shop or search_listings, so the routing guidance is not fully explicit.

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 description goes well beyond the readOnlyHint and openWorldHint annotations by explaining concrete consequences: promoted listings repeat, high-volume queries drift between pages, and listings can be missed or seen twice across a walk. This is exactly the kind of behavioral context an agent needs to avoid assuming stable pagination or complete coverage.

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 sentences with no filler. The core purpose is front-loaded, followed by a critical pagination caveat. Every sentence earns its place, and the structure makes the warning prominent.

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 tool with 14 optional parameters and 0% schema description coverage, the description is incomplete. It captures the core purpose and pagination pitfalls but offers no guidance on parameter combinations, defaults, or how to construct a valid search. The output schema exists, so return values are covered, but agent-facing invocation guidance remains thin.

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 carries the burden of explaining parameters, but it only vaguely references a 'search query'. It does not explain any of the 14 parameters such as sort, radius, ad_type, buy_now, min_price, max_price, category_id, or location_id. Parameter names and enums provide some self-evident meaning, but the description itself adds almost no semantic value.

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 resource ('listings') and operation ('matching a search query'), and clarifies it returns only 'one page' of results. It distinguishes itself from siblings like get_listing (single listing) and get_shop/find_* by focusing on search over listings. The wording is precise and immediately actionable.

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 implies this tool is for searching listings and that pagination is involved, but it does not explicitly say when to prefer it over alternatives such as get_listing, find_category, or find_location. It also does not mention when not to use it or how to resolve prerequisite IDs. Usage context is clear but exclusions and alternative routing are left to inference.

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