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

With only openWorldHint in annotations, the description carries most of the burden and does disclose the key non-obvious trait: this tool is stateful, and the first invocation behaves differently (baseline + full return) from subsequent ones. It omits anything about pagination limits or failure modes for unknown names, so it stops short of full 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?

Two short sentences, front-loaded with the core behavior and followed by the one edge case that would otherwise surprise a caller. No filler, no 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?

An output schema exists, so return-value detail is rightly omitted, and the stateful first-check behavior is covered. However, for a tool whose schema is entirely undocumented, leaving max_pages and the meaning of 'name' unexplained is a real gap an agent would hit at invocation time.

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% for both parameters. The description never mentions the required 'name' parameter or explains that it identifies the saved search, and 'max_pages' (default 2, max 5) is completely unaddressed despite directly governing result volume. A 0%-coverage schema needed the description to compensate and it does not.

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 ('Return listings') scoped to a saved search's check history, which cleanly separates it from siblings like search_listings, get_listings, and list_saved_searches. It does not name an alternative explicitly, but the resource qualifier does the differentiation work.

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 first-check semantics ('records a baseline and returns everything currently listed') give useful implied guidance about state and expected results, but there is no explicit when-to-use versus search_listings/get_listings, nor any prerequisite about the saved search needing to exist first.

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 destructiveHint annotation already flags this as a mutating operation, but the description adds real value by disclosing the cascading effect: the associated seen-listing history is also deleted. It does not state whether the deletion is reversible or requires special permissions, so it stops short of a 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 tightly worded sentence that front-loads the action and includes the cascade effect without padding. No wasted clauses, though it is very sparse.

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?

An output schema exists, so return-value detail is unnecessary, and the destructive annotation plus the cascade disclosure cover the key behavioral risk. The remaining gap is the unnamed/unexplained parameter and the absence of any irreversibility or error-condition context.

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 single parameter 'name' has 0% schema description coverage and the description never clarifies that it is the saved search's name, whether it is case-sensitive, or what happens on a mismatch. With low coverage, the description should compensate and does not.

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 (delete) and resource (saved search) plus an important secondary effect (seen-listing history). It is clearly distinguishable from save_search, check_saved_search, and list_saved_searches, though it never explicitly names a sibling for differentiation.

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?

"Delete" implies the use case, but there is no guidance on when to use this versus check_saved_search or list_saved_searches, no prerequisites, and no warning about conditions under which deletion should be avoided.

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 read-only and open-world behavior. The description adds substantial context beyond that: filter types (select, range, multi), the param/to_param pairing for range filters, and the limitation that extra_params can only set one value per key, requiring a browser workaround for multi-value filters.

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 dense and front-loaded: purpose first, then the mechanics of filter types and downstream usage. Every sentence earns its place, with no redundant or vague phrasing.

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 read-only list tool with an output schema and annotations, the description fully equips an agent to call it and use the results. It explains filter structure, the param mechanism, and special cases like multi-value filters, leaving no critical gaps 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%, so the single category_id parameter is already documented in the schema. The main description does not add further meaning or formatting details for this parameter, so 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?

States a specific verb and resource: 'List a category's own filters ... and their values.' It also distinguishes itself from siblings by explaining that filter params are used in search_listings' extra_params or in a URL for search_by_url/save_search.

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?

Explains the context for using the tool: filter params feed into search_listings, search_by_url, or save_search. It also gives a clear alternative for multi-value filters (use browser + search_by_url). However, it does not explicitly state when to use get_filters versus list_categories or get_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=true, so the read-only, external-fetch nature is covered. The description adds the list of returned facets, which is useful, but says nothing about auth requirements, rate limits, or error behavior for a missing listing.

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 tightly written sentence that front-loads the verb and resource and then lists the payload. No filler, no redundancy with 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?

With an output schema carrying return values and annotations covering the safety profile, the description only needs to convey purpose and scope, which it does. The only omission is any routing guidance versus the many sibling listing tools.

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 'item' parameter is already documented as a listing ID or full URL. The description adds no syntax, format, or lookup detail 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 ('Get') plus resource ('one listing') and enumerates the returned content (price, attributes, description, seller, images, dates). The singular 'one listing' implicitly distinguishes it from the sibling get_listings, but the description never names that sibling 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 'one listing' – an agent can infer this is for fetching a single known listing rather than searching. No explicit when-to-use, when-not, or pointer to siblings like search_listings or get_listings, so guidance is thin.

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 and openWorldHint, but the description adds genuinely new operational context: items are 'fetched one at a time, throttled', which warns the agent about latency/rate behavior. It does not, however, say what happens on partial failure or invalid IDs.

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 zero filler; the scope statement comes first and the usage rule second. Every clause 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 one-parameter batch read with an output schema, the description supplies the usage rule and the throttling caveat, which is everything an agent needs. Return-shape explanation is correctly omitted since an output schema exists.

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 fully documented in the schema ('Listing IDs or URLs, e.g. from a search result'), so the description adds no syntax or format detail beyond the word 'listings'. Baseline 3 applies when the schema carries the semantics.

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 full details of several listings') plus the batching scope ('in one call'), which cleanly separates it from the singular sibling get_listing. An agent can pick it without inspecting 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?

Explicitly names the alternative it replaces ('instead of calling get_listing repeatedly') and the triggering condition ('check a handful of candidates from a search'), so the selection rule is unambiguous.

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, covering the safety and network profile. The description adds the hierarchical listing behavior but says nothing about pagination, limits, or return ordering. 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?

Two short sentences, the core listing behavior front-loaded and the parameter effect second. Zero wasted words.

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?

An output schema exists so return values need no explanation, and the tool has a single optional parameter. The description covers what is listed and how the parameter alters scope; only minor operational details (ordering, item limits) are absent.

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, but the description goes beyond the schema field text by explaining that a category_id switches the call from top-level categories to that category's subcategories, clarifying the semantic effect of the parameter.

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 (List) and resource (list.am categories) and even states what is returned (ID and name). No sibling tool handles categories, so an agent can select this 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?

It gives a clear conditional: pass a category_id to get subcategories, omit it implicitly for top-level. There is no explicit when-not or named alternative, but the sibling set contains no competing category tool, so the guidance is sufficient for correct invocation.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the useful detail that each entry carries a last check time, but says nothing about ordering, volume, or whether unchecked searches are included.

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 or redundancy. It is appropriately sized for a simple read tool, though it is terse enough that nothing beyond the bare minimum is conveyed.

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?

An output schema exists, so return-value detail need not be repeated here, and with zero parameters there is little else to cover. The definition is complete enough to call correctly, missing only routing guidance relative to its siblings.

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 baseline is 4; there is nothing for the description to disambiguate. Schema coverage is 100% and the empty argument object matches the description's no-argument framing.

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

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

States a specific verb+resource (list saved searches) and adds the returned attribute (last check time). It does not distinguish itself from siblings like check_saved_search or get_listings, which is where a 5 would require explicit differentiation.

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 indication of when to use this versus the closely related check_saved_search, save_search, or delete_saved_search siblings, and no prerequisites or exclusions are given. Usage must be inferred entirely from the 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?

With no annotations, the description carries the full behavioral burden for a state-creating operation, yet it only states the end goal. It omits whether saving is idempotent, what happens on a duplicate name (the schema calls name 'unique' but the description never addresses collisions), whether the record persists server-side, and what errors can occur.

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, and the purpose is stated before the mechanism. It is efficient, though arguably too terse for a five-parameter creation 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?

An output schema exists, so return values need not be described, but for a 5-parameter mutation with no annotations and 40% schema coverage the description is too thin. It never covers the alternative parameter modes, name uniqueness behavior, or failure 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 40%: url and name are documented, but query, region_id, and category_id are bare. The description adds nothing about parameters and does not explain the two mutually exclusive input modes (a full URL vs. query/category_id/region_id) that the schema only hints at in the url field.

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+resource ('Save a search') and adds the downstream purpose (enabling check_saved_search to report only new listings), which distinguishes it from sibling read tools like search_listings and list_saved_searches. It stops short of explicitly contrasting with the other save/delete siblings, but the intent is unambiguous.

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 the causal link to check_saved_search ('so check_saved_search can report only new listings later'), which tells the agent when this tool matters. There is no explicit when-not guidance, no mention of prerequisites, and no statement about what to do if the search already exists.

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 safety and external-access profile are covered. The description adds one useful behavioral fact — filters in the URL are preserved — but says nothing about pagination (limit/max_pages), row compaction, or failure behavior on malformed URLs.

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 short sentence, front-loaded with the action and resource, and every word earns its place. No redundancy with the schema or annotations.

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?

An output schema exists, so return values need not be explained, and annotations cover the read/open-world profile. Still missing are pagination semantics for limit and max_pages and any hint about how URL-embedded filters interact with those caps, which matters for a 4-parameter 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?

Schema description coverage is 50%: url and full are documented, while limit and max_pages have no descriptions anywhere. 'Keeping all its filters' reinforces what the url parameter does, but the description does not compensate for the two undocumented pagination 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 states a specific verb (fetch) and resource (results for a list.am search URL) and adds the key qualifier 'keeping all its filters', so an agent understands this replays a saved URL rather than building a new query. It does not name search_listings as the alternative, but the URL-driven distinction is evident.

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 existing list.am search URL' tells the agent it needs a ready-made URL, which implies this is for replaying a search rather than constructing one. It never states when to prefer this over search_listings or get_listings, nor what happens without a valid list.am URL.

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=true. The description goes beyond that by disclosing that price filters are applied locally with approximate exchange rates — a non-obvious behavioral trait that explains result imperfection and motivates max_pages tuning.

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 tight sentences, purpose front-loaded, followed immediately by the one caveat that changes how an agent should call it. 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?

An output schema exists, so return values need no explanation, and all params are documented in the schema. The description covers the key non-obvious behavior; only sibling routing is missing for a 12-param open-world search 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?

Schema description coverage is 100%, so the schema already documents all twelve parameters thoroughly. The description reinforces the price_min/price_max semantics by explaining local application and approximate rates, but adds no format or syntax detail. 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 ('Search list.am listings') plus scope ('in any category'), so the agent knows exactly what it does. However, it never distinguishes itself from the sibling get_listings or search_by_url, which an agent facing nine sibling tools would need.

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 implies when to use it via the note about fetching more pages when filtering heavily, which is actionable operational advice. But there is no explicit when-not guidance or any routing to alternatives such as search_by_url or get_filters.

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