Marktplaats & 2dehands

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses concrete behavioral details: free, bidding-only and reserved ads are excluded, outliers beyond 1.5x IQR are trimmed, and statistics are based on the most relevant asking prices. This is genuine methodological transparency that an agent cannot infer from annotations.

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 dense sentences: the first front-loads the core purpose, the second explains exclusions and outlier trimming, and the third gives a practical reliability tip. No filler or repetition of schema details.

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 14-parameter tool with 100% schema coverage, an output schema, and safety annotations, this description is complete enough. It explains the computation, exclusions, and reliability considerations; return values are covered by the output schema, so no further explanation is needed.

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 the baseline is 3. The description adds meaningful guidance beyond the schema by recommending subcategory plus attributes over free-text query and explaining that free text drags in accessories. This helps an agent choose better parameter combinations.

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 specific verb and resource: it computes price statistics (min, quartiles, median, max, mean) and returns cheapest matches for a search. This is clearly distinct from sibling tools like search_listings or get_listing_details, so an agent can tell what the tool does 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 gives clear context for how to use the tool: it operates over a search and is most reliable with a subcategory plus attributes rather than free text. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide an 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavior: the tool is stateless, paid promotions are filtered out, and when results are truncated the cursor deliberately only advances to the oldest returned ad so no listing is skipped. This is exactly the kind of behavioral nuance an agent needs.

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 tight sentences, each earning its place: the core action, the cursor state protocol, and the truncation caveat. It is front-loaded and contains 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 the high-quality input schema, annotations, and output schema, the description covers the non-obvious usage contract completely: stateless polling, cursor advancement semantics, and the no-skip guarantee. Nothing essential for correct invocation 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?

Input schema coverage is 100%, with rich per-parameter descriptions, so the baseline is 3. The description adds the cursor/since relationship, but most parameter meaning already lives in the schema; no compensation is 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 uses a specific verb ('Poll') and resource ('listings'), and pinpoints the exact behavior: listings placed after a given moment, newest first, paid promotions filtered out. This clearly distinguishes it from general-purpose siblings like search_listings or list_seller_listings, even without naming 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?

The description gives clear operational context: poll incrementally by storing and passing the returned cursor as 'since'. It does not explicitly state when to prefer this over search_listings or other siblings, so it stops short of full when/when-not 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, and destructiveHint=false, so the safety profile is covered. The description is consistent with these hints and adds detail on the response contents, but it does not disclose additional behavioral traits such as rate limits or auth requirements.

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 dense sentence that front-loads the core action and resource, then efficiently lists all returned data categories. Every phrase adds value, and there is no filler 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?

Given a rich output schema, fully documented parameters, and annotations covering safety and idempotency, the description provides sufficient context for an agent to select and invoke the tool correctly. No critical behavioral or usage gap remains.

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 input schema already documents listing_id, site, and max_images fully. The description does not add parameter-level meaning beyond what the schema provides, 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?

The description uses a specific verb ('Fetch') and names the exact resource ('the full advertisement'), then enumerates the included fields. This clearly distinguishes it from sibling tools like get_seller_profile or search_listings, which target different resources or scopes.

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 explains what the tool returns but gives no explicit guidance on when to use it versus alternatives such as list_seller_listings or search_listings. There are no when-to-use, when-not-to-use, or exclusion statements.

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, and non-destructive behavior. The description adds the important interpretation that null means the marketplace does not report that signal, which helps the agent avoid misreading missing data as a problem.

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 deliver the core purpose, the null semantics, and a cross-reference to a sibling tool with no filler. Everything earns its place.

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?

Annotations cover safety and idempotency, an output schema exists, parameters are fully documented, and the description provides the one interpretive detail an agent needs: what null means. 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?

Schema description coverage is 100%, so parameters are already fully documented in the schema. The description does not add much beyond indicating the seller context; per the rubric, baseline 3 is appropriate when the schema carries the parameter-semantics 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?

Description opens with a specific verb-resource pair ('Look up a seller's trust signals') and enumerates concrete signal types. It also names list_seller_listings as the sibling for current offerings, which distinguishes this tool from a nearby alternative.

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 the tool is for trust/verification data rather than active listings, and explicitly points to list_seller_listings when the agent needs current offers. It provides a clear context signal, though it does not spell out exhaustive when-not-to-use conditions.

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 destructiveHint=false, and the description's 'Browse' aligns perfectly. The description adds context that the tree is shared between marktplaats.nl and 2dehands.be, which is useful beyond annotations. No contradiction.

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 core purpose, no filler. The description is precisely as long as needed.

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-only tool with one optional parameter, an output schema, and annotations covering safety, the description is complete. It tells the agent what the tool does and why it's useful, leaving no essential gaps.

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 schema fully documents the single `parent` parameter, including its nullability and semantics. The description adds no additional parameter detail beyond the schema, so with 100% schema coverage, a baseline 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 clearly states it browses a category tree shared across two marketplaces, with the explicit purpose of finding names/ids for search_listings filters. This distinguishes it from sibling tools by tying it to a specific downstream use.

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 explains when to use this tool: to obtain category names/ids for search_listings filters. It implies that it's the go-to for exploring the category hierarchy, though it doesn't explicitly mention alternatives or when not to use it. Still, the purpose is actionable.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful context about output semantics: valid values and per-value ad counts, plus the fact that filters apply to either a category or a search. No contradiction with annotations.

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 front-load the purpose, include concrete filter examples, and end with an actionable downstream instruction. Every sentence earns its place with no redundancy or 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 the rich output schema, complete parameter descriptions, and safety annotations, the definition is sufficiently complete. It explains what the tool returns and how to use the result, while the schema covers parameter defaults and relationships to list_categories.

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 fully documents all parameters. The description adds only a small semantic link between 'category or search' and the downstream use of labels, but it does not provide new parameter-level meaning.

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 ('Discover the filters available for a category or search') and a clear resource: filters with valid values and match counts. It also differentiates itself from siblings by explaining that the returned labels feed into search_listings' 'attributes' parameter.

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 clearly conveys when to use the tool: when you need the available filters for a category or query, and it shows how the result should be consumed downstream. It does not explicitly name alternatives or when-not-to-use conditions, so it stops short of a 5.

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, and destructiveHint=false, so the safety profile is covered. The description adds the 'currently has on offer' phrasing, implying real-time data, but does not disclose pagination behavior or result format beyond what the schema/output schema provide. It does not contradict annotations.

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 wasted words. The first sentence states the core purpose; the second lists practical use cases. It is front-loaded and efficient.

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 and 100% parameter coverage, the description only needs to add contextual value, which it does via use cases. It does not repeat schema details, and nothing essential for selecting or invoking the tool 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 fully documents all 8 parameters. The description adds no parameter-specific meaning beyond what the schema already states, which matches the baseline of 3 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 clearly states the resource ('everything one seller currently has on offer') and the implied verb 'list'. It is unambiguous about scope but does not explicitly differentiate from siblings like search_listings or get_seller_profile, though the 'one seller' scope distinguishes it naturally.

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 concrete use cases ('spot dealers posing as private sellers, duplicate or suspicious ads, and bundle deals'), giving clear context on when to use it. It does not state when not to use it or name alternatives, so it misses the exclusion 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a non-obvious behavioral default: 'Paid promotions are filtered out unless include_sponsored is set.' This goes beyond structured fields and clarifies an important hidden behavior without contradicting the annotations.

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 exactly two sentences with no filler. The main purpose is front-loaded, followed by a compact list of filter dimensions and a key behavioral default. Every sentence earns its place.

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 21 parameters, a rich output schema, and detailed per-parameter descriptions, the description provides adequate orientation: what it searches, which platforms, and a notable default. It could explicitly mention pagination or sorting, but those are already documented in the schema, so 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already explains every parameter thoroughly. The description's enumeration of filter types adds no syntax or format details beyond what each parameter description provides. It does not need to compensate for any gap.

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 a specific verb ('Search') and a specific resource ('second-hand listings on Marktplaats or 2dehands'), and enumerates the available filter dimensions. It is not a tautology and gives a concrete sense of the tool's role. However, it does not explicitly distinguish itself from sibling tools like list_seller_listings or check_new_listings, so it falls 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 description implies the tool is for finding listings by criteria, and the schema's parameter descriptions point to companion tools (list_categories, list_category_filters), providing indirect workflow guidance. There is no explicit 'use this when...' or 'use X instead when...' statement, so an agent must infer when to choose this over siblings.

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