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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the description is not burdened with basic safety disclosure. It still adds meaningful behavioral context: evidence quality is heuristic and the tool may abstain rather than produce a probability or certified valuation.

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, and the core action is front-loaded before the caveat. Every sentence contributes to purpose or behavioral expectation.

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

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

The tool has a required listing string and a large optional SearchRequest object with zero schema descriptions, yet the description does not explain either input. Output schema and annotations cover returns and safety, but the input guidance is far too thin for this complexity.

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 says nothing about the two parameters. It does not explain what format 'listing' expects or how the optional nested 'request' object and its many filters should be used, leaving the schema names to carry nearly all parameter 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 names a specific action and resource: compare an asking price against like-for-like ads. It also rules out treating the result as a certified valuation, but it does not distinguish this tool from siblings such as dv_compare or dv_similar.

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 phrase 'Compare asking price against like-for-like ads or abstain' implies the usage context, but the description gives no explicit when-to-use guidance and does not name any sibling alternative or exclusion condition.

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, idempotent, open-world, and non-destructive behavior. The description adds data-provenance context ('published public', 'simplified by the source helper') and a scope limitation ('not cadastral boundaries'), which is useful 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?

A single tight sentence with no filler, front-loading the core action and immediately adding a critical scope exclusion. 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?

The description explains what the tool returns and its data limitations but says nothing about how to use the city or district parameters, despite 0% schema description coverage. For a tool with non-trivial invocation options, this leaves a significant gap.

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

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

Schema description coverage is 0%, and the description never mentions the two parameters (city, district) or their defaults, formats, or meanings. It only implies that some location filtering exists via the resource name.

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) and resource (public neighbourhood outlines), and distinguishes the data type from cadastral boundaries. It does not name a sibling tool or explicitly route the agent, 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?

Provides a negative scope ('not cadastral boundaries') but no positive when-to-use guidance, no alternatives among the many dv_* siblings, and no prerequisites. The agent must infer the intended context.

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, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds a genuine behavioral commitment ('without inventing a conversion rate') and the rental Pareto-frontier output mode, which is useful context beyond the annotations, though it omits anything about limits, cost, or resolution of unresolved facts.

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 written sentences with the core action front-loaded and the rental special case second. No filler, though 'unresolved facts' is left undefined rather than being genuinely informative.

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 comparison tool with a single undocumented parameter, open-world behavior, and many overlapping siblings, the description leaves key questions unanswered: what counts as an 'unresolved fact', what the comparison yields, and how it differs from dv_rank/dv_similar.

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?

There is one parameter, 'listings', with 0% schema description coverage, so the schema does not compensate. The description implies the array can hold either ads or unresolved facts, which is meaningful input semantics, but it never clarifies the accepted format, identifiers, or the 10-item cap.

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 (compare) and resource (supplied ads), plus a distinctive behavior for rentals (deposit/rent Pareto frontier). However, it does not distinguish itself from the many similar siblings like dv_rank, dv_similar, or dv_assess_price, and 'unresolved facts' is unexplained jargon.

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 phrase 'For rentals' hints at a conditional mode, but there is no guidance on when to choose dv_compare over dv_rank, dv_similar, or dv_assess_price, and no prerequisites or exclusions are stated.

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

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

The description discloses that the count is either a public upstream approximation or an explicitly labelled returned-sample count, clarifying the nature of the result beyond the read-only annotations. This is valuable context not covered by structured fields.

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, and the key caveat is front-loaded. However, the phrasing is slightly cryptic, which reduces clarity despite the brevity.

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 a complex nested request object and an output schema, the description is far too sparse. It does not explain how to construct a count query, what fields support counting, or what the output represents.

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?

With 0% schema description coverage, the description must compensate by explaining parameters, but it provides no information about any of the request fields. It fails entirely to add meaning 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 mentions an 'approximate count' but never states what is being counted (listings, results, etc.). It does not provide a clear verb+resource pair that distinguishes it from siblings like dv_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?

It only warns that 'local constraints are not a source-wide count', which is a limitation, not guidance on when to use this tool versus alternatives. There is no explicit when-to-use or when-not-to-use 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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds real behavioral value by stating that only the publicly accessible first batch is returned and that permission failures surface explicitly as errors rather than being silently swallowed — a meaningful disclosure for a read against potentially restricted data.

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 compact sentence with the read scope front-loaded and no filler. It is tight, though the telegraphic style ("first batch") buys brevity at the cost of clarity.

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, and annotations cover the safety profile. What remains missing is material: the meaning of "first batch" and any pagination/continuation path, plus the semantics of brand_token. For a tool with essentially no schema documentation, the description leaves too much to inference.

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%: the single required parameter brand_token has only a regex pattern and no textual explanation, and the description never mentions it. The agent must guess that brand_token identifies the dealer/brand to summarize, so the description fails to compensate for the coverage 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 names a verb ("Read") and a resource ("a dealer page", "first batch"), so the general intent is inferable. However, "first batch" is cryptic — it's unclear whether this is a summary, a pagination chunk, or a preview — and it does not distinguish itself from the close sibling dv_seller_summary or the dv_get_listing/dv_get_listings family.

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 when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as dv_seller_summary or the listing tools. The only usage signal is the implicit "publicly accessible" qualifier, which the agent must interpret on its own.

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, the description adds important behavioral context: the export resource is bounded, owner-scoped, expires after one hour, and protects CSV cells against formula execution. It does not mention required permissions or rate-limit behavior, but it substantially improves transparency for a non-read-only creation tool.

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 text. Every phrase contributes either scope, lifetime, ownership, or CSV safety context.

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

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

The tool has an output schema, so return values need not be described, and the description covers key operational constraints. However, with a large nested request object and 0% schema descriptions, it leaves the request semantics and format options unexplained, creating clear 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 0%, so the description must compensate, but it does not explain the nested SearchRequest fields or clarify that the format parameter accepts both csv and jsonl. It only mentions CSV cells and formula protection, giving minimal parameter-related 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 names a specific verb and resource: 'Create a bounded, owner-scoped one-hour export resource.' It clearly frames the tool as an export-resource creator, though it does not explicitly say what results are being exported or contrast it with sibling search/list tools.

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 no explicit when-to-use guidance, no prerequisites, and no alternatives such as dv_search or dv_get_listings. Usage is only implied by the word 'export' and the Existence of a request parameter.

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, openWorldHint, and destructiveHint, so safety is covered by structured data. The second sentence adds a genuine non-obvious caveat — that presence of a filter schema does not guarantee enforcement at the source — which is useful behavioral context beyond the annotations, though the description still omits scope or return-shape details.

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

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

Two short sentences, front-loaded with the action and capped by a caveat. There is no filler, though the first sentence is terse to the point of ambiguity.

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. However, with 0% parameter coverage and a vague purpose on a discovery tool, the description leaves the inputs and the practical workflow incompletely specified.

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 both 'city' (default 'tehran') and the required 'category' are undocumented. The description implies a category is the key input but says nothing about what values are valid, what 'city' scopes, or the format expected, leaving the agent to guess both 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 verb 'Discover' plus resource 'category filter types and units' gives a rough sense of a metadata-introspection tool, but it's unclear what a 'filter schema' actually is or what the tool returns. Nothing in the description distinguishes it from siblings like dv_search or dv_count, so an agent must infer its role.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative named. The caveat sentence hints at a prerequisite (verify the source actually enforces a filter), but the agent is left to infer that this tool should be called before relying on filter behavior.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful scope by limiting results to public landmarks/places rather than personal addresses. It does not describe return behavior, coordinate behavior, or limitations beyond that scope.

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 compact sentence with the key scope constraint front-loaded. Every clause carries useful information, and there is 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?

The tool has an output schema and safety annotations, which reduce the description's burden. However, with 0% schema description coverage across three parameters, the description leaves important invocation details undocumented, especially the meaning and constraints of lat, lon, and query.

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 for parameter meaning. It implies that lat/lon define the map centre and that 'query' is a landmark/place search, but it does not explain coordinate defaults, valid ranges, coordinate system, or query semantics such as max length.

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 a public landmark/place near a map centre. It also clarifies the scope by excluding exact personal address lookup. However, it does not distinguish this tool from nearby siblings such as dv_nearby, dv_locate, or dv_place_mapping.

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 a negative usage condition ('not an exact personal address lookup') and implies usage when searching for public landmarks near a map centre. It does not name alternatives or explain when to use this tool instead of sibling geospatial tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructiveness, so the safety profile is covered. The description still adds genuine behavioral context beyond that: results preserve missing/false/zero values rather than coercing them, rent and deposit are kept separate, and only public data is returned.

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 dense sentence that front-loads the action and resource, then appends the two output-fidelity caveats. Nothing is wasted, though the phrasing is terse enough to read as a checklist.

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 shape need not be described, and the description covers purpose, accepted input forms, and result-fidelity quirks. The only real omission is the meaning and effect of the refresh parameter.

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 schema contributes nothing about parameter meaning. The description partially compensates by explaining that 'listing' accepts a token or an HTTPS divar.ir URL, but the 'refresh' boolean is left entirely unexplained in both description and 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 ('Read') and resource ('public details of a token or HTTPS divar.ir listing URL'), which is clear and distinguishable from the plural sibling dv_get_listings. It stops short of explicitly naming the sibling to route against, so it lands at 4 rather than 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 accepted input forms (token or HTTPS URL) imply when the tool applies, but there is no explicit when-to-use, no when-not, and no reference to alternatives such as dv_get_listings or dv_search. Usage is inferable but not stated.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive semantics. Beyond that, the description discloses a genuinely useful partial-failure contract: each member gets an 'independent result or actionable error,' so one bad listing doesn't fail the batch. It does not explain the 'refresh' behavior, but the per-member error semantics are real added value.

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 batch scope and per-member behavior are stated immediately. Appropriately sized for a simple tool, though terse enough to leave gaps.

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 needn't be described, and annotations carry the safety profile. The description covers batch semantics and per-member error handling but omits any explanation of 'refresh' and any usage routing, leaving the definition just adequate.

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 carry parameter meaning. It restates the listings count constraint (1-10), which is already encoded as minItems/maxItems in the schema, and says nothing about what the 'refresh' boolean does. It fails to compensate for the coverage 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?

States a specific verb (Read) and resource (listings) with a clear batch scope of 1-10. The batch count implicitly distinguishes it from the singular sibling dv_get_listing, but no sibling is named explicitly, so differentiation is left to inference.

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

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

No when-to-use guidance, no exclusions, and no reference to alternatives like dv_get_listing or dv_search. Batch usage is only implied by the '1-10' phrasing.

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 annotations already declare this as read-only, idempotent, non-destructive, and open-world. The description adds a useful caveat that location accuracy is source-dependent, which goes beyond the annotations, though it does not discuss failure modes or endpoint behavior in detail.

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 language. It efficiently states the operation and one important behavioral caveat.

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 lookup with rich annotations and an output schema, the description covers purpose and a reliability caveat. However, it does not compensate for the missing parameter descriptions or provide usage guidance relative to sibling 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 description coverage is 0%, so the description must compensate. It only says 'a point' and does not explain that the parameters are latitude and longitude, their expected format, coordinate order, or the numeric bounds already shown in 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: resolve a point to its city/district. It is clear what the tool does, but it does not explicitly distinguish itself from similar siblings such as dv_geocode or dv_nearby.

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 the tool is for looking up a point's city/district, but gives no explicit guidance on when to use it versus alternatives or when not to use it. No sibling tool is referenced.

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 (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description discloses real behavior: sampling is capped at one point per UTC day, history begins only at first recording, and composition changes are explicitly not treated as item-price changes. These are meaningful caveats an agent cannot derive from the annotations alone.

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 dense sentences with the core capability front-loaded and the caveats trailing. Nothing is padded, though the second sentence is compact to the point of being cryptic about how composition changes relate to price data.

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 whose main parameter is an 18-field nested search request, the description supplies almost no guidance on scoping the request or interpreting the returned history. The output schema covers return values, but the input side and the relationship to dv_price_history remain unexplained.

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 `request` parameter is a large nested SearchRequest object (city, sort, limit, pages, filters, constraints, price bounds, etc.) with no field documentation anywhere. The description only implicitly touches the `record` flag via the record/read duality and never explains what `request` controls.

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+resource: 'Record one asking-price sample per UTC day or read saved points,' making the dual write/read nature clear. It does not, however, distinguish this tool from the sibling dv_price_history, leaving the agent to guess which price-history tool to pick.

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 two modes ('record' vs 'read saved points') are named, implying the `record` flag selects the path, but there is no explicit when-to-use, when-not, or named alternative (e.g. dv_price_history). Usage is only inferable.

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 annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds that sale/rent/deposit filters are independent and that coverage is reported, which is useful context beyond annotations, but it does not discuss auth needs, rate limits, or sampling limitations.

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 written sentences with no filler. Purpose is front-loaded in the first sentence and the filtering/coverage behavior follows 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?

Given a required nested request object with many fields, 0% schema description coverage, and a large sibling set, the description is too thin to guide correct invocation. Output schema exists, so return-value explanation is not required, but input and usage context are largely 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 0%, and the nested SearchRequest contains many fields with no schema-level explanation. The description only gestures at category/transaction and sale/rent/deposit filtering, leaving city, sort, limits, price bounds, constraints, and other parameters unexplained.

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 what the tool does: describe asking-price samples by category/transaction, with independent sale/rent/deposit filtering and coverage reporting. The resource and scope are clear, though the verb 'Describe' is somewhat vague and the description does not differentiate it from siblings such as dv_market_history or dv_count.

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?

Provides no when-to-use guidance, no exclusions, and no alternatives among the many sibling tools. It only describes filtering behavior, leaving the agent to infer when this snapshot tool is preferable to dv_market_history, dv_count, or dv_assess_price.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real behavioral context beyond them: coordinates/distances may be approximate, and unsupported providers fail explicitly rather than silently returning 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 tight sentences with the core scope front-loaded and the caveats secondary. No filler, though the second sentence packs accuracy and error behavior together and could be slightly clearer.

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 carry the safety profile. What's missing is parameter-level meaning for a 5-param, 0%-coverage schema and any routing guidance among 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 description coverage is 0% across 5 parameters, so the description must compensate but does not. It only hints at lat/lon ('near a point') and radius ('distances') and says nothing about 'category', 'query', or the coordinate bounds baked into 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 resource and scope: 'Public map listings near a point,' which tells an agent this is a proximity/geospatial listing retrieval. However, it never differentiates itself from close siblings like dv_neighbours or dv_get_listings, so the agent must infer which proximity tool to pick.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as dv_neighbours for an adjacent-listing use case. The agent is left to infer applicability purely from the name and one-sentence description.

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. However, the description adds no behavioral context beyond them – 'distinct bases preserved' is undefined and conveys nothing about output shape, ordering, or spatial semantics.

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?

It is a single sentence and the action is front-loaded, which is good. But the second half is cryptic filler that does not earn its place by adding meaning.

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

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

An output schema exists so return values need not be described, but for a tool with zero schema description coverage and no annotation-supplied context, the description leaves required-parameter behavior and city defaulting entirely unexplained.

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% across two parameters, and the description says nothing about either. It never explains that district_id is required, nor that city defaults to 'tehran', leaving the agent with no semantics beyond raw types.

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 recognizable verb ('List') and resource ('adjacent and nearby neighbourhoods'), but the trailing clause 'with the helper's distinct bases preserved' is opaque jargon that does not clarify scope. It also fails to distinguish itself from close siblings like dv_nearby and dv_boundaries, leaving the agent unsure which spatial tool to pick.

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 when-to-use guidance, no prerequisites, and no mention of alternatives despite siblings dv_nearby and dv_boundaries overlapping heavily with this tool. The agent must infer the selection condition entirely on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered externally. The description adds one genuinely useful behavioral fact — that the parser is Persian-language and domain-scoped to amounts/categories/amenities — but says nothing about determinism, failure modes, or what happens with text it cannot resolve.

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 extraction targets front-loaded; no filler. However, "Review assumptions and unresolved text" is cryptic and reads like an instruction to the agent rather than a description of the tool, slightly muddling an otherwise tight statement.

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, return values need not be explained. But for a parsing tool embedded in a large search family, the description omits the crucial relationship to dv_search and whether its output is meant to be fed forward, which is the main thing an agent needs to place this tool 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 description coverage is 0% for the single "text" parameter, so the schema contributes only type and length bounds. The description hints the content is Persian and parseable into amounts/categories/amenities, but never states that "text" is the free-text query to be parsed or its expected form, leaving the one required parameter under-specified.

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 ("Parse") and enumerates exactly what is extracted: Persian amounts, category intent, and required/preferred amenities. That is far more informative than a tautology, though it never names the downstream sibling (dv_search) that consumes the parsed result, so differentiation from siblings is left to inference.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The description never states that this is a pre-processing step feeding dv_search, nor what input should trigger it, so an agent must guess its place in the workflow.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add one behavioral fact beyond that - unresolved identifiers stay unverified (partial success rather than hard failure) - but says nothing about error handling, limits, or what 'unverified' means downstream.

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 zero filler; the input->output mapping comes first and the edge-case clause is compactly appended. Nothing could be removed without losing 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile, so the core is adequate. Still missing is any hint about input shape/validity or what an agent should do with 'unverified' results, which matters for a mapping tool used in a pipeline.

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 the single required 'ids' parameter, so the description carries the burden and does partially explain it: the ids are legacy public place identifiers. However it omits format details (integer array, 1-50 items) that the schema also leaves unlabeled, so compensation is only partial.

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 ('Map') and both resources (old public place identifiers -> current IDs), so the agent knows exactly what transformation happens. It is distinguishable from lookup siblings like dv_geocode or dv_locate, though it never explicitly contrasts itself with dv_resolve_entities, which sounds related.

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 reach for this tool versus alternatives such as dv_resolve_entities or dv_geocode, and no prerequisites or exclusions are given. Usage is only inferable from the phrase 'old public place identifiers', which is context rather than 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results are ordered from the first observation — but says nothing about pagination or how the limit caps the series.

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 scope statement front-loaded ahead of the disambiguation. No filler, though the terse phrasing leaves the critical listing-identifier semantics unaddressed rather than merely brief.

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 safety. However, the caller must supply a 'listing' identifier and a 'limit' with no guidance on either, which is the main completeness gap for an otherwise simple read 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 0% for both parameters, so the description carries the full burden and does not meet it. It never explains the format of 'listing' (ID? URL? address?) nor what 'limit' (default 90, max 100) bounds — number of observations, days, or pages.

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 this owner's observations of this listing') plus a scope qualifier ('starting at first observation'). The closing clause implicitly distinguishes it from dv_market_history, though it never names the sibling it is not.

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 negative framing ('It is not a retroactive market index') implies the alternative exists but never names it or states a positive when-to-use condition. An agent can infer the tool returns owner-recorded observations rather than market data, but must guess at the boundary versus dv_market_history or dv_get_listing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful non-annotation fact — that monthly_deposit_rate is an assumption rather than a market fact, and that only 'supported' price evidence is used. It says nothing about the ranking algorithm, tie-breaking, or determinism, so credit stops at 3.

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 with no waste; the ranking basis is front-loaded and the caveat follows. Efficient and readable, though the terseness is partly why key semantics (mode) go unexplained rather than because everything necessary was said.

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?

This is a high-complexity tool: a nested SearchRequest with dozens of fields (price/deposit bounds, filters, constraints, sort, strict), a mode enum, and a nested data type. With 0% schema coverage and an output schema present (so return values need not be explained), the description still omits the mode semantics and the dependency on a prior search. For this complexity, it is substantially under-specified.

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 full burden and largely fails it. It clarifies only monthly_deposit_rate (an assumption), while the four mode enum values (best_fit, best_value, cheapest, deals) — the primary control over behavior — are never mentioned or explained, nor is the request/constraints structure. Only one of three top-level params gets any semantic help.

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 the verb 'rank' and the basis ('explicit preferences and supported price evidence'), which is more specific than a tautology. However, the resource is described only as 'the scanned sample', an unexplained term — it never says what entity is being ranked (listings?) or where the sample came from. Adequate but leaves the agent guessing at the object of the operation.

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?

No when-to-use guidance and no routing to alternatives, despite 30+ siblings including dv_search, dv_compare, dv_assess_price and dv_similar that an agent must choose between. It does not say whether a prior scan/search is a prerequisite or how ranking relates to comparison. Nothing beyond an implicit 'use this to rank'.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds one genuinely useful behavioral note — that available options vary by configured provider — which explains variable results the annotations cannot convey. It stops short of describing return shape or failure behavior, so a 3 is appropriate.

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 with the primary action front-loaded and no filler. Every clause carries 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?

An output schema exists, so return values need not be explained. However, for a four-parameter tool with 0% schema description coverage and no usage guidance, the description does not say enough about how to combine kind with query/city/category to be callable with confidence.

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% across four parameters, so the description must carry the load, but it only loosely gestures at the kind enum values via 'city/district/category names or canonical model keys.' It says nothing about the query or category parameters, nor about how city interacts with the rest, so the 0% coverage gap is only partially compensated.

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 (resolve) and resources (city/district/category names, canonical model keys), which is more informative than a bare name restatement. It does not, however, differentiate itself from any of the ~30 sibling dv_ tools, so an agent still has to infer where resolution fits in the pipeline.

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 call this versus alternatives, nor any prerequisite such as 'use before search to resolve a name into a key.' 'Options depend on the configured provider' is a caveat, not usage guidance, so the agent gets no routing help.

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 annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior, so the description does not need to repeat safety details. It adds some context about bounded coverage, explicit unknowns, and draining buffered results, but these points remain abstract and do not fully explain the search behavior.

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-loads the search concept before the pagination instruction. It is not padded, though the first sentence is abstract and does not fully earn its place without more concrete detail.

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?

This is a complex search tool with a required request object containing many nested fields and 0% schema description coverage. The description mentions pagination and result qualifiers, and the output schema reduces the need to explain returns, but it remains far too incomplete about how to construct the search request.

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 explain the parameters, but it mentions only next_cursor while the actual top-level parameter is cursor. It provides no explanation of the required request object or any of its many search fields such as query, filters, city, price bounds, and constraints.

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 search verb and adds vague qualifiers about evidence, unknowns, and bounded coverage, but it never names the resource being searched or the domain. It also does not distinguish dv_search from siblings such as dv_parse_search, dv_filter_schema, or dv_get_listings.

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

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

The only usage guidance is about passing next_cursor with the same query to drain buffered results. It gives no explicit when-to-use guidance versus alternatives and does not explain when this search tool is preferable to related sibling tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the description is not obligated to cover safety. It adds genuinely useful behavior: no authentication required, no phone lookup, and critically no fallback or retry when access is denied, which tells the agent not to expect alternative resolution paths.

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 with zero filler; the core purpose is front-loaded ahead of the access/failure constraints. Every clause carries 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. However, a required input parameter is left entirely undefined in both schema and description, which is a real gap for a single-argument lookup 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 0% for the sole required parameter 'listing', and the description never mentions it. The agent cannot tell whether 'listing' is an ID, URL, address, or free-text query, so the description fails to compensate for the coverage 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?

States a specific verb (Read) and resource (public seller summary), and the 'seller' qualifier distinguishes it from the sibling dv_dealer_summary. The 'where available' scoping is a useful clarification, though it never says what entity the summary is resolved from.

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

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

The description implies usage through availability and failure constraints ('where available', 'no fallback on access denial') but never states explicitly when to choose this over dv_dealer_summary or dv_get_listing. Guidance is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior. The description adds genuine behavioral context beyond that: it rejects unknown/different critical specs and explains exclusions. However, it doesn't define what a "critical spec" is or how exclusions surface (though the output schema may cover returns).

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, front-loaded with the core purpose and zero filler. Size is appropriate, though the second clause is somewhat cryptic given the complex schema it fronts.

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

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

The schema is complex with a nested SearchRequest, Constraints objects, and many tunable fields at 0% description coverage; two sentences cannot adequately explain how `listing` seeds the comparison or how the request modifiers interact. An output schema exists, so return values needn't be covered, but input completeness is poor.

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 bears full burden. It only characterizes the optional `request` as narrowing the sample and leaves `listing` (the required anchor) and the nested request fields (constraints, strict, verify_details, filters, price bounds) entirely unelaborated.

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 like-for-like items") and adds a scoping constraint ("reject unknown/different critical specs"). It is distinguishable from generic search siblings but does not name any specific alternative among the ~30 tools.

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?

"Optional request narrows the sample" hints at how the request arg behaves, but there is no explicit when-to-use versus dv_search, dv_nearby, or dv_compare, and no stated prerequisites or exclusions. The agent must infer the selection criteria from the tool name 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful caveat beyond that: the reported configuration is local/capability-oriented and should not be treated as confirming live connectivity. It does not, however, say whether budget values are cached or how fresh scheduler config is.

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 shown, followed by the single most important caveat. Nothing is padded and nothing relevant is buried.

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

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

With an output schema present, the description need not describe return values, and with zero parameters there are no inputs to explain. Combined with the rich annotations, the definition is nearly self-sufficient; only the absence of any when-to-use guidance keeps it from being fully 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly does not invent inputs.

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 concrete verb ("Show") and enumerates the resources returned: provider capabilities, local budget, and scheduler configuration. It is clearly an introspection/status tool and cannot be confused with any sibling, all of which are domain operations (search, listings, watch, geocode). It stops short of a crisp one-line identity, but the purpose 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?

There is no statement of when to call this versus the other 29 dv_* tools, nor prerequisites or sequence guidance. The clause "Does not claim live connectivity" sets expectations about the data rather than helping an agent choose between tools. Usage is only loosely implied.

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 declare idempotentHint=false, yet the description asserts 'retries are idempotent' – a direct conflict on the single most important behavior for a retry-prone ack call. It also omits whether acks are persistent or auth is required despite openWorldHint=true. This is an annotation 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?

A single tight sentence with a front-loaded verb and a secondary constraint; nothing is padded. 'Only this owner's' is slightly awkward phrasing but still information-bearing.

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, but for a mutating tool with an open-world hint and an undocumented required array parameter, the description should clarify scope, expected id range, and auth/permission needs. It resolves none of these.

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?

There is one parameter (event_ids) with 0% schema description coverage, so the description carries the full burden and largely fails: it mentions 'events' generically but never explains that event_ids is a 1–100 element array of string identifiers, nor their format.

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 ('acknowledge') and resource ('received events'), plus an ownership scope ('only this owner's'). It is decipherable against siblings like dv_watch_events and dv_watch_delete, though it never names an alternative to sharpen the boundary.

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?

No explicit guidance on when to acknowledge versus re-reading via dv_watch_events, deleting via dv_watch_delete, or checking via dv_watch_check. The watch-workflow context ('received events') implicitly suggests post-consumption use, but no condition or exclusion is stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the mutation profile is covered. The description does add genuine behavioral context beyond them: the enqueue step is atomic and the scan continuation advances only after enqueuing, which explains ordering and statefulness. It still omits failure behavior, whether re-running is safe, and what a 'bounded chunk' means.

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

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

A single dense sentence with the scan action and its side effect front-loaded; there is no filler. It is arguably too terse for a non-idempotent stateful operation, but every word 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?

An output schema exists, so return values need not be explained, and the core loop (scan chunk, enqueue, advance continuation) is conveyed. However, for a non-read-only, non-idempotent, open-world tool the description says nothing about when to call it repeatedly, when to stop, or how it pairs with dv_watch_ack.

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 for watch_id and does not meet it. It implies watch_id selects the 'watch chunk' but never states the format constraint (32-char lowercase hex) or where a valid watch_id comes from. With only one parameter the gap is small in absolute terms, but nothing is compensated.

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 specific verbs and a resource: scan a bounded watch chunk, enqueue events, advance the scan continuation. It is far more informative than the name alone, but it never differentiates itself from siblings like dv_watch_events or dv_watch_ack, and 'watch chunk' is internal jargon an agent may not decode.

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 when-to-use or when-not-to-use guidance, no mention of alternatives, and no indication of how this relates to dv_watch_events, dv_watch_ack, or dv_watch_list. The agent must infer the polling/scan role from the wording 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 write (readOnlyHint=false), non-idempotent, non-destructive, open-world. The description adds two pieces of genuine behavior beyond them: the watch requires an external worker to run checks, and existing results form a baseline unless explicitly included. It still omits lifecycle details (how long the watch persists, how interval_seconds governs execution), so the added context is real but thin.

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 short sentences with the action front-loaded and no filler. It is efficient, though for a tool with five parameters and a nested request object the terseness edges toward under-specification rather than disciplined concision.

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. However, the tool has high input complexity (nested SearchRequest, five params, 0% schema coverage) and the description says almost nothing about the parameters or the watch lifecycle, leaving meaningful 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 0%, so the description must carry parameter meaning, and it barely does. 'Unless explicitly included' gestures at include_existing, but name, request, recheck_missing, and interval_seconds are entirely unexplained, and the nested SearchRequest shape is never addressed.

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 ('Persist ... watch') plus a scope qualifier ('owner-scoped'), which is more than a tautology of the name. It does not, however, distinguish itself from the other dv_watch_* siblings (update/list/delete/check), so an agent gets the what but not the why-this-one.

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?

'A worker must run checks' implies the watch is passive and that a separate check mechanism (likely dv_watch_check) is required, which is useful implied guidance. But there is no explicit when-to-use versus dv_watch_update/list/delete, and no stated prerequisites or exclusions.

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

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

Annotations already declare destructive=true and idempotent=true, so the safety profile is covered. The description still earns credit by disclosing effects beyond the annotations: the seen set is destroyed along with the watch, and already-enqueued events survive for audit/delivery. Auth requirements and reversibility are not addressed, keeping it 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 sentence with the destructive action front-loaded and the retention caveat placed after a semicolon. No filler, no repetition of the name 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 shape needn't be described, and annotations cover the destructive/idempotent profile. The description covers the two things an agent most needs for a delete: what is destroyed and what survives. Only permission/auth prerequisites are 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 0%, so the description must carry the parameter burden, but it only hints at the target via 'this owner's watch'. The schema's regex pattern supplies ID format, and watch_id is the sole required param, so the baseline of 3 applies with no compensating detail.

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

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

States a specific verb (delete) and resource (the watch and its seen set), and adds the scope 'this owner's'. It is clearly distinguishable from the create/list/update/check/ack siblings by the verb alone, though it never names an alternative 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 implied by 'Delete this owner's watch' but there is no stated when-to-use, when-not-to-use, or comparison against siblings such as dv_watch_ack or dv_watch_update. The agent must infer that this is the terminal teardown operation.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: that consumption uses an independent per-caller cursor and that reading leaves events in place, which matters for a watch/queue tool.

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 core action is front-loaded and the non-destructive caveat follows 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?

An output schema exists, so return values need not be explained. However, with zero parameter documentation, no guidance on cursor advancement relative to after_seq, and no routing to sibling tools, the definition is only minimally sufficient for calling this tool 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 description coverage is 0% for three parameters (limit, watch_id, after_seq), so the description carries the full burden. 'Delivery cursor' loosely gestures at after_seq, but limit, watch_id, and the 1-100 bound/defaults are entirely undocumented, leaving the agent to infer them from the schema 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?

States a specific verb and resource ('Read durable events') plus the mechanism ('independent delivery cursor'), which is enough to separate it from the write-oriented watch siblings (dv_watch_create, dv_watch_ack, dv_watch_delete). It does not name a sibling explicitly, so it falls short of full 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?

Usage is only implied: the note that reading 'does not acknowledge or remove events' hints that dv_watch_ack is the tool for acknowledgement, but the description never states when to choose this tool over dv_watch_check, dv_watch_list, or dv_watch_ack.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact – that results are restricted to the invoking owner – but says nothing about ordering, rate limits, or what an empty list means.

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

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

A single front-loaded sentence with no filler. The scope qualifier ('only this owner's') appears before the returned fields, which is the right ordering.

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 re-explained, and annotations carry the safety profile; for a zero-parameter read tool this is nearly complete. The only gap is the absence of any routing hint among the many dv_watch_* 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. The schema is empty and 100% covered; the description correctly adds no parameter detail because there is none to add.

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 ('this owner's saved watches'), and names the fields it surfaces (continuation, coverage, last error). An agent can distinguish it from dv_watch_events or dv_watch_check, though the description never explicitly names those siblings to reinforce the distinction.

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?

'only this owner's' is a scoping statement, not usage guidance. Nothing tells the agent when to prefer this over dv_watch_events, dv_watch_check, or dv_watch_create, and no prerequisites or exclusions are given.

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

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

Annotations already flag a non-destructive mutation (destructiveHint=false, readOnlyHint=false), and the description adds genuinely new behavioral context: the pending scan and seen versions survive the change. It stops short of noting idempotency or what happens if interval_seconds is unchanged.

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 zero filler. The preservation guarantee is stated immediately after the action, which is the right ordering for an agent deciding whether this tool is safe.

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 safety profile is covered by annotations plus the preservation clause. However, for a two-parameter mutation with no schema descriptions, the missing parameter guidance leaves a real gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does not. It never names watch_id or interval_seconds, gives no units, and omits the 60–604800 second bounds and the 32-hex-char watch_id pattern.

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 ('Change a watch interval') and adds a scope qualifier that distinguishes it from a delete-and-recreate workflow. It does not name a sibling tool, but the mutation target 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: use this to alter an existing watch's interval rather than recreating it. There is no explicit statement of when to prefer this over dv_watch_delete plus dv_watch_create, and no prerequisites or exclusions are given.

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